DOCUMENTATIONv2

POST

Public entropy

Request protected sample

/api/v2/entropy/samples

AUTHENTICATIONBearer token · entropy:writeAUTHORITATIVE OWNERentropy-serviceCONTRACT AUTHORITYGenerated Rust OpenAPISTATUSSource ready · production listed

PURPOSE + BUSINESS CONTEXT

Request a bearer-authorized entropy or noise sample carrying an Ed25519 proof from the physical entropy source.

WHEN THIS CALL IS USEFUL

Use after current-key discovery with a fresh 16–128 character caller nonce and the minimum exact byte count needed by an application-specific randomness model.

OUTCOME · Create or advance

What changes

Consumes one idempotent source request and returns bounded physical material plus a source-signed evidence envelope. It creates no key, beacon round, lottery result, oracle decision, transaction, or business authority.

WHY IT MATTERS

Gives people and agents a contract-backed way to advance protected sample.
Provides bounded, nonce-bound physical entropy with a verifiable source envelope while keeping source credentials and private signing material isolated.

ISOLATION + AUTHORITY

Caller authorization, nonce, requested byte count, physical source, source key, signed envelope, consumer conditioning, application randomness model, and downstream cryptographic use remain distinct. A valid source signature proves envelope provenance and integrity, not fitness for every cryptographic protocol or permission to perform a downstream action.

BEFORE YOU CALL

Authenticate at the documented boundary: bearer+scope.
Supply the required kind (body), bytes (body), encoding (body), assurance (body), client_nonce (body) exactly as defined by the live contract.
Use one Idempotency-Key only for retries of the same byte-equivalent logical mutation.
Resolve the required assurance and byte count, fetch the current source key, generate a fresh caller nonce, and define the consuming application's conditioning and replay policy.

WHAT TO DO NEXT

Verify the sample envelope against the current source key, including the source ID, key ID, nonce echo, byte count, signature, and freshness.
Pass accepted bytes only into the application-specific randomness construction; do not reuse the nonce or infer downstream authorization.

AGENT GUIDANCE

Use protected sample only for the purpose and lifecycle stage described by this operation; do not treat it as authority for an adjacent action.
Supply the required kind (body), bytes (body), encoding (body), assurance (body), client_nonce (body) exactly as defined by the live contract.
Validate source ID, key ID, signature, nonce echo, byte count, encoding, freshness, and replay posture, then apply the consuming application's required conditioning and health policy.
After a timeout or conflict, read authoritative state before deciding whether an equivalent retry is safe.

MACHINE CONTRACT

The exact deployed parameters, schemas, responses, security requirements, and Hybrid-Chain agent metadata are authoritative at this operation's production OpenAPI JSON Pointer. The readable tables below add integration guidance; the deployed OpenAPI controls if guidance and the machine contract ever differ.

Open the authoritative production contract ↗

EXTENDED INTEGRATION GUIDANCE

Readable request and response reference

Examples illustrate integration intent; the referenced OpenAPI operation and component schemas define the executable shape.

PARAMETERS

Headers, path, query, and body

NAMELOCATIONPRESENCETYPE / RULES / PURPOSE

AuthorizationheaderRequired

Bearer tokenCredential containing the entropy:write scope.EXAMPLEBearer hc_live_…

Idempotency-KeyheaderRequired

ASCII string · 1–128Caller-generated key reused for every retry of the same logical mutation.EXAMPLEentropy-sample-20260901-001

kindbodyRequired

entropy | noiseConditioned entropy output or a validation-noise sample.EXAMPLEentropy

bytesbodyRequired

integer · entropy 1–65536; noise 1–4096Exact decoded byte count requested from the physical source.EXAMPLE32

encodingbodyRequired

base64 | hexRepresentation of sample.value; it does not alter the underlying sample bytes.EXAMPLEbase64

assurancebodyRequired

source_signedRequire the only supported assurance: an Ed25519 source-signed envelope.EXAMPLEsource_signed

client_noncebodyRequired

URL-safe string · 16–128Caller nonce bound into the signed envelope; generate a fresh value for each logical request.EXAMPLEclient_nonce_01K4QSE000000001

REQUEST

JSON body example

{
  "kind": "entropy",
  "bytes": 32,
  "encoding": "base64",
  "assurance": "source_signed",
  "client_nonce": "client_nonce_01K4QSE000000001"
}

RESPONSES

Status and payload examples

200Bounded sample, digest, source-chain link, and independently verifiable Ed25519 proof.Mutation completed · JSON RESPONSE+

{
  "data": {
    "schema": "hybrid.entropy.sample.v2",
    "request_id": "entropy-sample-20260901-001",
    "client_nonce": "client_nonce_01K4QSE000000001",
    "source_id": "qse-production-1",
    "source_key_id": "qse-ed25519-7kYp9bW2Qn4rT8cD",
    "sequence": 184225,
    "previous_record_sha256": "0000000000000000000000000000000000000000000000000000000000000000",
    "generated_at": "2026-09-01T18:24:00Z",
    "generated_at_unix": 1788287040,
    "assurance": "source_signed",
    "sample": {
      "kind": "entropy",
      "encoding": "base64",
      "bytes": 32,
      "value": "base64-sample-bytes",
      "sha256": "1111111111111111111111111111111111111111111111111111111111111111"
    }
  },
  "proof": {
    "algorithm": "Ed25519",
    "canonicalization": "hybrid-json-v1",
    "key_id": "qse-ed25519-7kYp9bW2Qn4rT8cD",
    "signature": "base64url-signature",
    "record_sha256": "2222222222222222222222222222222222222222222222222222222222222222"
  }
}

INTEGRATION DECISION

CALLER ACTION: Accept the returned representation or receipt, then verify the sample envelope against the current source key, including the source ID, key ID, nonce echo, byte count, signature, and freshness.
RETRY SAFETY: Do not repeat a successful mutation merely to confirm it. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Persist returned identifiers, versions, commitments, and receipts. Refresh the entropy record and compare request nonce, source identity, byte count, digest, signing key, assurance, and retention commitment.

400Idempotency-Key or the JSON body is missing or malformed.Request must change · JSON RESPONSE+

{
  "code": "missing_idempotency_key",
  "message": "Idempotency-Key or the JSON body is missing or malformed."
}

INTEGRATION DECISIONmissing_idempotency_key

CALLER ACTION: Rebuild the request from the live OpenAPI operation and correct the rejected method, media type, header, parameter, or body field.
RETRY SAFETY: Do not retry the same invalid request. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Compare the submitted values with the documented constraints before another call. Refresh the entropy record and compare request nonce, source identity, byte count, digest, signing key, assurance, and retention commitment.
ESCALATE WHEN: Escalate when source proof, digest, signature, key identity, assurance, or replay state fails verification; never substitute unverified randomness.

401The bearer credential is missing or invalid.Authentication required · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "The bearer credential is missing or invalid."
}

INTEGRATION DECISIONinvalid_credentials

CALLER ACTION: Discard the rejected credential, complete the documented authentication or reassertion flow, and rebuild any request signature with fresh timestamps and nonces.
RETRY SAFETY: Retry only with a newly valid credential and fresh replay-protection values. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Assume the outcome is unknown only when the connection failed after transmission; otherwise authentication failed before domain work. Refresh the entropy record and compare request nonce, source identity, byte count, digest, signing key, assurance, and retention commitment.
ESCALATE WHEN: Escalate when source proof, digest, signature, key identity, assurance, or replay state fails verification; never substitute unverified randomness.

403The credential lacks exact entropy:write authority.Authority or policy denied · JSON RESPONSE+

{
  "code": "insufficient_scope",
  "message": "The credential lacks exact entropy:write authority."
}

INTEGRATION DECISIONinsufficient_scope

CALLER ACTION: Verify the exact scope, tenant or workspace membership, owner boundary, step-up purpose, feature policy, and resource eligibility. Never broaden authority automatically.
RETRY SAFETY: Do not retry until the missing authority or policy condition has been deliberately resolved with least privilege.
STATE RECONCILIATION: Confirm the caller and resource resolve to the same authority boundary for bounded entropy requests, source identity, assurance level, digests, signatures, and retained verification evidence.
ESCALATE WHEN: Escalate when source proof, digest, signature, key identity, assurance, or replay state fails verification; never substitute unverified randomness.

409The idempotency key or source request was already consumed with conflicting state.State reconciliation required · JSON RESPONSE+

{
  "code": "entropy_idempotency_conflict",
  "message": "The idempotency key or source request was already consumed with conflicting state."
}

INTEGRATION DECISIONentropy_idempotency_conflict

CALLER ACTION: Stop the mutation sequence and fetch the latest authoritative resource, lifecycle state, version, ETag, reservation, or existing idempotency result.
RETRY SAFETY: Retry only after reconciling the conflict. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Refresh the entropy record and compare request nonce, source identity, byte count, digest, signing key, assurance, and retention commitment.
ESCALATE WHEN: Escalate when source proof, digest, signature, key identity, assurance, or replay state fails verification; never substitute unverified randomness.

422The kind, byte count, encoding, assurance, or client nonce is invalid.Request must change · JSON RESPONSE+

{
  "code": "entropy_request_rejected",
  "message": "The kind, byte count, encoding, assurance, or client nonce is invalid."
}

INTEGRATION DECISIONentropy_request_rejected

CALLER ACTION: Rebuild the request from the live OpenAPI operation and correct the rejected method, media type, header, parameter, or body field.
RETRY SAFETY: Do not retry the same invalid request. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Compare the submitted values with the documented constraints before another call. Refresh the entropy record and compare request nonce, source identity, byte count, digest, signing key, assurance, and retention commitment.
ESCALATE WHEN: Escalate when source proof, digest, signature, key identity, assurance, or replay state fails verification; never substitute unverified randomness.

502The source returned an unexpected payload, digest, key identity, record hash, or signature.Dependency unavailable or outcome uncertain · JSON RESPONSE+

{
  "code": "invalid_entropy_source_proof",
  "message": "The source returned an unexpected payload, digest, key identity, record hash, or signature."
}

INTEGRATION DECISIONinvalid_entropy_source_proof

CALLER ACTION: Preserve the exact request and treat the outcome as uncertain until authoritative state proves whether it committed.
RETRY SAFETY: Reconcile before retrying. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions. Use bounded backoff with jitter.
STATE RECONCILIATION: Refresh the entropy record and compare request nonce, source identity, byte count, digest, signing key, assurance, and retention commitment.
ESCALATE WHEN: Escalate when source proof, digest, signature, key identity, assurance, or replay state fails verification; never substitute unverified randomness.

503The configured physical entropy source is unavailable.Dependency unavailable or outcome uncertain · JSON RESPONSE+

{
  "code": "entropy_source_unavailable",
  "message": "The configured physical entropy source is unavailable."
}

INTEGRATION DECISIONentropy_source_unavailable

CALLER ACTION: Preserve the exact request and treat the outcome as uncertain until authoritative state proves whether it committed.
RETRY SAFETY: Reconcile before retrying. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions. Use bounded backoff with jitter.
STATE RECONCILIATION: Refresh the entropy record and compare request nonce, source identity, byte count, digest, signing key, assurance, and retention commitment.
ESCALATE WHEN: Escalate when source proof, digest, signature, key identity, assurance, or replay state fails verification; never substitute unverified randomness.

OPERATIONAL NOTES

Security and lifecycle guarantees

Verify the response before use: match request_id and client_nonce; match source_id and both key IDs to GET /api/v2/entropy/source-key; decode sample.value; confirm bytes and sample.sha256; canonicalize data as hybrid-json-v1; verify proof.signature; and recompute proof.record_sha256.
Reuse Idempotency-Key only for a retry of the same logical request. A fresh key and nonce request new physical material. The gateway and source reject replay or conflicting state rather than silently substituting another sample.
Never use the returned bytes directly as a private key. Apply the downstream protocol's required derivation, domain separation, health tests, contributor model, and failure handling. Keep sample values out of URLs, prompts, analytics, logs, and shared caches.
sequence and previous_record_sha256 support source-record continuity checks; they are not a public beacon, proof that no records were withheld, or evidence of how a downstream application used the sample. Responses are no-store.

DOCUMENTATION STATUS

This route is implemented in canonical gateway source and appears in the production OpenAPI snapshot observed 2026-09-11T06:35:11.572Z. Authentication, tenant, feature, venue, and market policy still apply.

Verify the exact production OpenAPI operation ↗Return to the V2 directory ↗