{ "components": { "schemas": { "DrawMeta": { "properties": { "bytes_consumed": { "minimum": 1, "type": "integer" }, "policy": { "example": "CP2", "type": "string" }, "source": { "enum": [ "avalanche" ], "type": "string" } }, "required": [ "source", "policy", "bytes_consumed" ], "type": "object" }, "DrawRequest": { "discriminator": { "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/RawDrawRequest" }, { "$ref": "#/components/schemas/IntegersDrawRequest" }, { "$ref": "#/components/schemas/FloatsDrawRequest" }, { "$ref": "#/components/schemas/ShuffleDrawRequest" }, { "$ref": "#/components/schemas/WeightedDrawRequest" }, { "$ref": "#/components/schemas/UuidsDrawRequest" } ] }, "DrawResponse": { "properties": { "data": { "description": "Encoded string for `raw`, or array of drawn primitives." }, "kind": { "enum": [ "raw", "integers", "floats", "shuffle", "weighted", "uuids" ], "type": "string" }, "meta": { "$ref": "#/components/schemas/DrawMeta" }, "receipt": { "$ref": "#/components/schemas/Receipt" } }, "required": [ "kind", "data", "meta" ], "type": "object" }, "ErrorResponse": { "properties": { "reason": { "type": "string" }, "status": { "type": "string" } }, "required": [ "status" ], "type": "object" }, "FloatsDrawRequest": { "properties": { "count": { "maximum": 1024, "minimum": 1, "type": "integer" }, "kind": { "const": "floats", "type": "string" }, "max": { "default": 1.0, "type": "number" }, "min": { "default": 0.0, "type": "number" }, "nonce": { "default": null, "maxLength": 128, "minLength": 1, "type": [ "string", "null" ] }, "sign": { "default": false, "description": "Attach an Ed25519 `AS-RECEIPT-V1` origin receipt.", "type": "boolean" } }, "required": [ "kind", "count" ], "type": "object" }, "IntegersDrawRequest": { "properties": { "count": { "maximum": 1024, "minimum": 1, "type": "integer" }, "kind": { "const": "integers", "type": "string" }, "max": { "type": "integer" }, "min": { "type": "integer" }, "nonce": { "default": null, "maxLength": 128, "minLength": 1, "type": [ "string", "null" ] }, "replacement": { "default": true, "type": "boolean" }, "sign": { "default": false, "description": "Attach an Ed25519 `AS-RECEIPT-V1` origin receipt.", "type": "boolean" }, "step": { "default": 1, "minimum": 1, "type": "integer" } }, "required": [ "kind", "min", "max", "count" ], "type": "object" }, "KeyRequestIn": { "properties": { "email": { "format": "email", "maxLength": 254, "type": "string" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" }, "tier_interest": { "enum": [ "free", "pro", "enterprise" ], "type": "string" }, "use_case": { "maxLength": 2000, "minLength": 1, "type": "string" } }, "required": [ "email", "name", "use_case", "tier_interest" ], "type": "object" }, "KeyRequestOut": { "properties": { "status": { "enum": [ "received" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "PubkeyResponse": { "properties": { "algorithm": { "enum": [ "Ed25519" ], "type": "string" }, "key_id": { "maxLength": 16, "minLength": 16, "type": "string" }, "public_key_base64": { "type": "string" }, "public_key_hex": { "maxLength": 64, "minLength": 64, "type": "string" } }, "required": [ "algorithm", "key_id", "public_key_hex", "public_key_base64" ], "type": "object" }, "QuotaErrorResponse": { "properties": { "limit_bytes": { "type": "integer" }, "remaining_bytes": { "type": "integer" }, "reset_at": { "format": "date-time", "type": "string" }, "status": { "enum": [ "quota_exceeded" ], "type": "string" } }, "required": [ "status", "limit_bytes", "remaining_bytes", "reset_at" ], "type": "object" }, "RandomResponse": { "properties": { "bytes": { "description": "Lowercase hex or standard base64 encoded bytes.", "type": "string" }, "receipt": { "$ref": "#/components/schemas/Receipt" } }, "required": [ "bytes" ], "type": "object" }, "RawDrawRequest": { "properties": { "bytes": { "maximum": 65536, "minimum": 1, "type": "integer" }, "encoding": { "default": "hex", "enum": [ "hex", "base64" ], "type": "string" }, "kind": { "const": "raw", "type": "string" }, "nonce": { "default": null, "maxLength": 128, "minLength": 1, "type": [ "string", "null" ] }, "sign": { "default": false, "description": "Attach an Ed25519 `AS-RECEIPT-V1` origin receipt.", "type": "boolean" } }, "required": [ "kind", "bytes" ], "type": "object" }, "Receipt": { "properties": { "payload": { "$ref": "#/components/schemas/ReceiptPayload" }, "signature_base64": { "type": "string" }, "signature_hex": { "maxLength": 128, "minLength": 128, "type": "string" }, "version": { "enum": [ "AS-RECEIPT-V1" ], "type": "string" } }, "required": [ "version", "payload", "signature_hex", "signature_base64" ], "type": "object" }, "ReceiptPayload": { "properties": { "bytes_consumed": { "minimum": 1, "type": "integer" }, "endpoint": { "enum": [ "/v1/random", "/v1/draw", "/v1/sandbox/draw" ], "type": "string" }, "issued_at": { "format": "date-time", "type": "string" }, "key_id": { "maxLength": 16, "minLength": 16, "type": "string" }, "nonce": { "type": [ "string", "null" ] }, "output_sha256": { "maxLength": 64, "minLength": 64, "type": "string" }, "policy": { "example": "CP2", "type": "string" }, "receipt_id": { "format": "uuid", "type": "string" }, "request_sha256": { "maxLength": 64, "minLength": 64, "type": "string" }, "source": { "enum": [ "avalanche" ], "type": "string" } }, "required": [ "bytes_consumed", "endpoint", "issued_at", "key_id", "nonce", "output_sha256", "policy", "receipt_id", "request_sha256", "source" ], "type": "object" }, "ShuffleDrawRequest": { "properties": { "items": { "items": {}, "maxItems": 512, "minItems": 2, "type": "array" }, "kind": { "const": "shuffle", "type": "string" }, "nonce": { "default": null, "maxLength": 128, "minLength": 1, "type": [ "string", "null" ] }, "pick": { "maximum": 512, "minimum": 1, "type": "integer" }, "sign": { "default": false, "description": "Attach an Ed25519 `AS-RECEIPT-V1` origin receipt.", "type": "boolean" } }, "required": [ "kind", "items" ], "type": "object" }, "StatusResponse": { "properties": { "conditioning": { "enum": [ "HMAC-SHA-256" ], "type": "string" }, "health_gate": { "enum": [ "sp800-90b-rct-apt" ], "type": "string" }, "policy": { "example": "CP2", "type": "string" }, "pool_state": { "enum": [ "healthy", "low", "empty" ], "type": "string" }, "signing_key_id": { "type": [ "string", "null" ] }, "source": { "enum": [ "avalanche" ], "type": "string" }, "status": { "enum": [ "ready", "degraded", "empty" ], "type": "string" } }, "required": [ "status", "pool_state", "source", "policy", "conditioning", "health_gate", "signing_key_id" ], "type": "object" }, "UuidsDrawRequest": { "properties": { "count": { "default": 1, "maximum": 256, "minimum": 1, "type": "integer" }, "kind": { "const": "uuids", "type": "string" }, "nonce": { "default": null, "maxLength": 128, "minLength": 1, "type": [ "string", "null" ] }, "sign": { "default": false, "description": "Attach an Ed25519 `AS-RECEIPT-V1` origin receipt.", "type": "boolean" } }, "required": [ "kind" ], "type": "object" }, "WeightedChoiceItem": { "properties": { "id": { "maxLength": 128, "minLength": 1, "type": "string" }, "weight": { "minimum": 1, "type": "integer" } }, "required": [ "id", "weight" ], "type": "object" }, "WeightedDrawRequest": { "properties": { "choices": { "items": { "$ref": "#/components/schemas/WeightedChoiceItem" }, "maxItems": 256, "minItems": 2, "type": "array" }, "count": { "default": 1, "maximum": 256, "minimum": 1, "type": "integer" }, "kind": { "const": "weighted", "type": "string" }, "nonce": { "default": null, "maxLength": 128, "minLength": 1, "type": [ "string", "null" ] }, "replacement": { "default": true, "type": "boolean" }, "sign": { "default": false, "description": "Attach an Ed25519 `AS-RECEIPT-V1` origin receipt.", "type": "boolean" } }, "required": [ "kind", "choices" ], "type": "object" } }, "securitySchemes": { "BearerAuth": { "description": "Managed API key (`as_live_...`). Never expose in browser bundles.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Conditioned avalanche entropy from a physical noise source. Served bytes are one-time. An optional Ed25519 signature is an AS-RECEIPT-V1 entropy receipt, not a verifiable random function.", "title": "Analog Seed", "version": "1.3.0" }, "openapi": "3.1.0", "paths": { "/v1/draw": { "post": { "description": "Turns serve-once avalanche bytes into raw, integers, floats, a shuffle, a weighted choice, or UUID version 4. Integer ranges use bitmask rejection, not modulo. Leftover rejection bytes are discarded. sign=true attaches an Ed25519 AS-RECEIPT-V1 entropy receipt.", "operationId": "draw_v1_draw_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrawRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrawResponse" } } }, "description": "Unbiased primitive derived from serve-once avalanche bytes.", "headers": { "X-AS-Policy": { "description": "Conditioning credit policy of the served segment(s), e.g. 'CP2' or 'CP1,CP2'.", "schema": { "example": "CP2", "type": "string" } }, "X-AS-Quota-Limit": { "description": "Daily byte quota for managed API keys (omitted for unlimited keys).", "schema": { "type": "integer" } }, "X-AS-Quota-Remaining": { "description": "Remaining bytes in the caller's own UTC daily quota.", "schema": { "type": "integer" } }, "X-AS-Quota-Reset": { "description": "UTC timestamp when the caller's daily quota resets.", "schema": { "format": "date-time", "type": "string" } }, "X-AS-Source": { "description": "Declared physical entropy source ('avalanche').", "schema": { "example": "avalanche", "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request body, parameter out of range, or body larger than 64 KiB." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, malformed, or invalid Bearer API key." }, "429": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/QuotaErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "description": "Daily byte quota exceeded (`quota_exceeded`) or per-minute rate limit reached (`rate_limited`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Entropy pool temporarily exhausted (`empty`) or signing key unavailable." } }, "security": [ { "BearerAuth": [] } ], "summary": "Draw an unbiased primitive", "tags": [ "Entropy" ] } }, "/v1/keys/request": { "post": { "description": "Stores a key request for the operator. Does not issue a secret.", "operationId": "request_key_v1_keys_request_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyRequestIn" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyRequestOut" } } }, "description": "API key request recorded." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid email, name, use_case, or tier_interest." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Disallowed browser `Origin` header." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too many key requests from this IP (`rate_limited`)." } }, "summary": "Request an API key", "tags": [ "Access" ] } }, "/v1/pubkey": { "get": { "description": "Public key used to verify AS-RECEIPT-V1 entropy receipts. Not a VRF key.", "operationId": "pubkey_v1_pubkey_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PubkeyResponse" } } }, "description": "Active Ed25519 public key for offline verification of `AS-RECEIPT-V1` receipts." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Ed25519 receipt signing is not configured on this instance." } }, "summary": "Ed25519 receipt public key", "tags": [ "Transparency & Verification" ] } }, "/v1/random": { "get": { "description": "Draws 1 to 65536 serve-once bytes from the conditioned avalanche pool. format is raw, hex, or base64. sign=true attaches an Ed25519 AS-RECEIPT-V1 entropy receipt and is rejected for format=raw.", "operationId": "random_bytes_v1_random_get", "parameters": [ { "description": "Number of conditioned serve-once bytes to draw (1 to 65536).", "in": "query", "name": "bytes", "required": true, "schema": { "maximum": 65536, "minimum": 1, "type": "integer" } }, { "description": "Output encoding: `hex` (default), `base64`, or `raw` (`application/octet-stream`).", "in": "query", "name": "format", "required": false, "schema": { "default": "hex", "enum": [ "hex", "base64", "raw" ], "type": "string" } }, { "description": "Attach an Ed25519 `AS-RECEIPT-V1` origin receipt (`hex` or `base64` only). Not a VRF.", "in": "query", "name": "sign", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Optional caller-supplied printable ASCII nonce (1 to 128 chars) bound into the receipt.", "in": "query", "name": "nonce", "required": false, "schema": { "maxLength": 128, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RandomResponse" } }, "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "Serve-once conditioned avalanche entropy.", "headers": { "X-AS-Policy": { "description": "Conditioning credit policy of the served segment(s), e.g. 'CP2' or 'CP1,CP2'.", "schema": { "example": "CP2", "type": "string" } }, "X-AS-Quota-Limit": { "description": "Daily byte quota for managed API keys (omitted for unlimited keys).", "schema": { "type": "integer" } }, "X-AS-Quota-Remaining": { "description": "Remaining bytes in the caller's own UTC daily quota.", "schema": { "type": "integer" } }, "X-AS-Quota-Reset": { "description": "UTC timestamp when the caller's daily quota resets.", "schema": { "format": "date-time", "type": "string" } }, "X-AS-Source": { "description": "Declared physical entropy source ('avalanche').", "schema": { "example": "avalanche", "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid query parameter or `sign=true` combined with `format=raw`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, malformed, or invalid Bearer API key." }, "429": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/QuotaErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "description": "Daily byte quota exceeded (`quota_exceeded`) or per-minute rate limit reached (`rate_limited`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Entropy pool temporarily exhausted (`empty`) or signing key unavailable." } }, "security": [ { "BearerAuth": [] } ], "summary": "Serve conditioned avalanche bytes", "tags": [ "Entropy" ] } }, "/v1/sandbox/draw": { "post": { "description": "Same primitives as /v1/draw with a 64-byte ceiling, no API key, and a silent pool reserve. Real avalanche bytes, not a software PRNG.", "operationId": "sandbox_draw_v1_sandbox_draw_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrawRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrawResponse" } } }, "description": "Small public sample of real conditioned avalanche entropy.", "headers": { "X-AS-Policy": { "description": "Conditioning credit policy of the served segment(s), e.g. 'CP2' or 'CP1,CP2'.", "schema": { "example": "CP2", "type": "string" } }, "X-AS-Source": { "description": "Declared physical entropy source ('avalanche').", "schema": { "example": "avalanche", "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid parameters or request exceeds sandbox per-call limits." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Disallowed or missing browser `Origin` header." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Sandbox IP rate limit or daily public budget reached (`sandbox_rate_limited`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Sandbox paused to protect the reserved API key pool (`sandbox_paused`)." } }, "summary": "Draw a small public sample", "tags": [ "Public Sandbox" ] } }, "/v1/status": { "get": { "description": "Coarse readiness of the avalanche pool. Does not report inventory, device identifiers, sites, or schedules.", "operationId": "status_v1_status_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" } } }, "description": "Coarse service readiness and active conditioning policy." } }, "summary": "Public service status", "tags": [ "Transparency & Verification" ] } } } }