{ "openapi": "3.1.2", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Sun Terminal Rider–Waite Tarot consultation API", "version": "1.0.0", "description": "An anonymous atomic consultation that fixes a complete Rider–Waite permutation and orientations, then returns identities and orientations without question text, meanings, or interpretation." }, "servers": [ { "url": "https://sunterminal.net" } ], "paths": { "/api/v1/consult": { "post": { "operationId": "createTarotEncounter", "summary": "Create one final Rider–Waite Tarot encounter", "description": "No authentication is required. Send application/json with no query parameters and a fresh lowercase UUIDv7 Idempotency-Key. The key must be less than 24 hours old and no more than 5 minutes ahead of the server clock. The body is limited to 8 KiB, unknown fields are rejected, count defaults to 1 and ranges from 1 through 78, and optional labels must be the exact ordered generic sequence position-1 through position-N. Question text and production seeds are not accepted. Retrying the same canonical request and key returns the exact stored response; changing canonical input under that key returns idempotency_conflict. A newly acquired pending encounter has a 30-second ownership lease. Reaching the deadline only makes the pending row eligible for a later matching request to conditionally record terminal failure; time passing alone does not run a background transition. A terminal failed encounter returns encounter_failed, is not retryable, has no Retry-After header, and will not be redrawn under that key. Sun Terminal does not create or recommend a replacement consultation. Results contain card identities and upright or reversed orientations, not meanings or interpretation. The anonymous limiter counts 10 attempts per 60 seconds for each connecting IP at each Cloudflare location; it is not exact global accounting. Failed rows retain a failure timestamp and one of two bounded internal failure classifications through the existing 24-hour active window, without exception details or public exposure of the internal classifications. Active D1 rows are deleted by hourly cleanup after the 24-hour retry window; Cloudflare D1 Time Travel may retain recoverable history after active deletion depending on the platform plan and configuration. Browser requests from another origin are not supported because the operation sends no CORS access-control headers.", "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "A freshly generated lowercase UUIDv7. Preserve it for every retry of this encounter; never replace it after an uncertain commit.", "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "./schemas/consult-request-v1.schema.json" }, "examples": { "minimal": { "value": { "schema_version": "sun-terminal.consult-request@1", "instrument": { "id": "tarot.rider-waite", "version": 1 }, "structural_inputs": {} } }, "threeCard": { "value": { "schema_version": "sun-terminal.consult-request@1", "instrument": { "id": "tarot.rider-waite", "version": 1 }, "structural_inputs": { "count": 3, "position_labels": [ "position-1", "position-2", "position-3" ] } } } } } } }, "responses": { "200": { "description": "One final sealed encounter result.", "headers": { "Content-Type": { "required": true, "schema": { "type": "string", "const": "application/json; charset=utf-8" } }, "Cache-Control": { "required": true, "schema": { "type": "string", "const": "no-store" } }, "Link": { "required": true, "description": "Discover the OpenAPI service description and HTML service documentation.", "schema": { "type": "string", "const": "; rel=\"service-desc\"; type=\"application/json\", ; rel=\"service-doc\"; type=\"text/html\"" } } }, "content": { "application/json": { "schema": { "$ref": "./schemas/consult-response-v1.schema.json" }, "examples": { "illustrative": { "value": { "schema_version": "sun-terminal.consult-response@1", "encounter_id": "enc_00000000000000000000000000000005", "status": "final", "instrument": { "id": "tarot.rider-waite", "version": 1, "manifest_digest": { "algorithm": "sha-256", "value": "cf2f783870880f60d35b8274039e577501c998d8cbf67eef8888fb1ea8220f0b" } }, "raw_result": { "schema_version": "sun-terminal.tarot.raw-result@1", "structural_inputs": { "count": 3, "position_labels": [ "position-1", "position-2", "position-3" ] }, "positions": [ { "position": { "index": 1, "label": "position-1" }, "card_id": "pentacles-03", "orientation": "upright" }, { "position": { "index": 2, "label": "position-2" }, "card_id": "swords-01", "orientation": "upright" }, { "position": { "index": 3, "label": "position-3" }, "card_id": "major-13", "orientation": "reversed" } ], "permutation_commitment": { "kernel": { "id": "committed-permutation", "version": 2 }, "deck": { "id": "rider-waite", "version": 1 }, "derivation": { "id": "hkdf-sha256-counter-stream", "version": 1, "hash": "sha-256", "seedEncoding": "32-byte-raw-from-64-lowercase-hex", "saltUtf8": "sun-terminal/tarot/hkdf-sha256-counter-stream/v1", "shuffleInfoPrefixUtf8": "sun-terminal/tarot/committed-permutation@2/rider-waite@1/shuffle/fisher-yates-rejection@1", "orientationInfoPrefixUtf8": "sun-terminal/tarot/committed-permutation@2/rider-waite@1/orientation/position-word-parity@1", "infoEncoding": "utf8-prefix-nul-uint32-be-page-counter", "shuffleStream": "shuffle", "orientationStream": "orientation", "pageBytes": 512, "pageCounterStart": 0, "wordEncoding": "uint32-be" }, "shuffle": { "id": "fisher-yates-rejection", "version": 1 }, "orientation": { "id": "position-word-parity", "version": 1 }, "canonicalization": { "id": "sun-terminal-tarot-permutation-json", "version": 2 }, "permutationHash": { "algorithm": "sha-256", "value": "c9d9d1909297ba936913b6c78162faeb733eb426ef234cfc35b6139fda3a5d2b" } }, "raw_result_hash": { "algorithm": "sha-256", "canonicalization": { "id": "sun-terminal-tarot-raw-result-json", "version": 1 }, "value": "9fffa308351b95bb79bd68dd2a2aefc5cbcfb3c2cd3d0e6f6518e673021b1c43" } }, "receipt": { "schema_version": "sun-terminal.encounter-receipt@1", "encounter": { "id": "enc_00000000000000000000000000000005", "status": "final", "committed_at": "2026-08-01T00:00:00.000Z", "finalized_at": "2026-08-01T00:00:01.000Z" }, "draw_facts": { "instrument": { "id": "tarot.rider-waite", "version": 1 }, "raw_result": { "schema_version": "sun-terminal.tarot.raw-result@1", "structural_inputs": { "count": 3, "position_labels": [ "position-1", "position-2", "position-3" ] }, "positions": [ { "position": { "index": 1, "label": "position-1" }, "card_id": "pentacles-03", "orientation": "upright" }, { "position": { "index": 2, "label": "position-2" }, "card_id": "swords-01", "orientation": "upright" }, { "position": { "index": 3, "label": "position-3" }, "card_id": "major-13", "orientation": "reversed" } ], "permutation_commitment": { "kernel": { "id": "committed-permutation", "version": 2 }, "deck": { "id": "rider-waite", "version": 1 }, "derivation": { "id": "hkdf-sha256-counter-stream", "version": 1, "hash": "sha-256", "seedEncoding": "32-byte-raw-from-64-lowercase-hex", "saltUtf8": "sun-terminal/tarot/hkdf-sha256-counter-stream/v1", "shuffleInfoPrefixUtf8": "sun-terminal/tarot/committed-permutation@2/rider-waite@1/shuffle/fisher-yates-rejection@1", "orientationInfoPrefixUtf8": "sun-terminal/tarot/committed-permutation@2/rider-waite@1/orientation/position-word-parity@1", "infoEncoding": "utf8-prefix-nul-uint32-be-page-counter", "shuffleStream": "shuffle", "orientationStream": "orientation", "pageBytes": 512, "pageCounterStart": 0, "wordEncoding": "uint32-be" }, "shuffle": { "id": "fisher-yates-rejection", "version": 1 }, "orientation": { "id": "position-word-parity", "version": 1 }, "canonicalization": { "id": "sun-terminal-tarot-permutation-json", "version": 2 }, "permutationHash": { "algorithm": "sha-256", "value": "c9d9d1909297ba936913b6c78162faeb733eb426ef234cfc35b6139fda3a5d2b" } }, "raw_result_hash": { "algorithm": "sha-256", "canonicalization": { "id": "sun-terminal-tarot-raw-result-json", "version": 1 }, "value": "9fffa308351b95bb79bd68dd2a2aefc5cbcfb3c2cd3d0e6f6518e673021b1c43" } } }, "provenance": { "request_fingerprint": { "algorithm": "sha-256", "canonicalization": { "id": "sun-terminal-consult-request-json", "version": 1 }, "value": "5555555555555555555555555555555555555555555555555555555555555555" }, "instrument_manifest": { "id": "tarot.rider-waite", "version": 1, "digest": { "algorithm": "sha-256", "value": "cf2f783870880f60d35b8274039e577501c998d8cbf67eef8888fb1ea8220f0b" }, "deck_digest": { "algorithm": "sha-256", "value": "f5c0a09c2e012f3716ca8b43c8976040054ced76cab350545d6b1f53b1b02c4e" }, "kernel_profile_digest": { "algorithm": "sha-256", "value": "40c5cc0973a8ab47a9aa261f63a44cdfbe3e82ccc92ac807358a9f7775ab7d34" } }, "kernel": { "identity": { "id": "committed-permutation", "version": 2 }, "profile_digest": { "algorithm": "sha-256", "value": "40c5cc0973a8ab47a9aa261f63a44cdfbe3e82ccc92ac807358a9f7775ab7d34" } }, "deck": { "identity": { "id": "rider-waite", "version": 1 }, "content_digest": { "algorithm": "sha-256", "value": "f5c0a09c2e012f3716ca8b43c8976040054ced76cab350545d6b1f53b1b02c4e" } }, "entropy": { "source": "web-crypto-get-random-values", "bits": 256, "draw_samples": 1, "seed_disclosure": "not-disclosed", "seed_persistence": "not-persisted", "independent_noncuration_proof": false }, "runtime": { "id": "sun-terminal-worker", "version": 1, "authenticity": "unsigned-service-assertion", "independent_origin_verification": false } }, "rendering": { "instrument_url": "https://sunterminal.net/instruments/tarot-rider-waite" }, "interpretations": [], "policy": { "replay": { "classification": "stored-final-result-retrieval-only", "independent_exact_replay": false, "terminal_exact_rederivation": false }, "privacy": { "question_text_accepted": false, "question_text_retained": false, "seed_disclosed": false, "encounter_public": false, "receipt_payload_in_telemetry": false }, "retention": { "profile": "anonymous-idempotency-24h", "active_record_expires_at": "2026-08-02T00:00:00.000Z", "retained": [ "idempotency-key-digest", "request-fingerprint", "resolved-manifest", "final-response" ], "not_retained": [ "raw-idempotency-key", "question-text", "draw-seed", "auth-headers" ] } } }, "instrument_url": "https://sunterminal.net/instruments/tarot-rider-waite" } } } } } }, "400": { "description": "The JSON or request contract is invalid. Stable codes: invalid_json, invalid_request.", "headers": { "Content-Type": { "required": true, "schema": { "type": "string", "const": "application/json; charset=utf-8" } }, "Cache-Control": { "required": true, "schema": { "type": "string", "const": "no-store" } }, "Link": { "required": true, "description": "Discover the OpenAPI service description and HTML service documentation.", "schema": { "type": "string", "const": "; rel=\"service-desc\"; type=\"application/json\", ; rel=\"service-doc\"; type=\"text/html\"" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./schemas/error-v1.schema.json" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_json", "invalid_request" ] } } } } } ] }, "examples": { "invalid_json": { "value": { "schema_version": "sun-terminal.error@1", "error": { "code": "invalid_json", "message": "The request body must be valid JSON.", "retryable": false } } }, "invalid_request": { "value": { "schema_version": "sun-terminal.error@1", "error": { "code": "invalid_request", "message": "Content-Type must be application/json.", "retryable": false } } } } } } }, "404": { "description": "The requested instrument id is unavailable. Stable codes: instrument_not_found.", "headers": { "Content-Type": { "required": true, "schema": { "type": "string", "const": "application/json; charset=utf-8" } }, "Cache-Control": { "required": true, "schema": { "type": "string", "const": "no-store" } }, "Link": { "required": true, "description": "Discover the OpenAPI service description and HTML service documentation.", "schema": { "type": "string", "const": "; rel=\"service-desc\"; type=\"application/json\", ; rel=\"service-doc\"; type=\"text/html\"" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./schemas/error-v1.schema.json" }, { "properties": { "error": { "properties": { "code": { "enum": [ "instrument_not_found" ] } } } } } ] }, "examples": { "instrument_not_found": { "value": { "schema_version": "sun-terminal.error@1", "error": { "code": "instrument_not_found", "message": "The requested instrument is not available.", "retryable": false } } } } } } }, "405": { "description": "The operation requires POST. Stable codes: method_not_allowed.", "headers": { "Content-Type": { "required": true, "schema": { "type": "string", "const": "application/json; charset=utf-8" } }, "Cache-Control": { "required": true, "schema": { "type": "string", "const": "no-store" } }, "Link": { "required": true, "description": "Discover the OpenAPI service description and HTML service documentation.", "schema": { "type": "string", "const": "; rel=\"service-desc\"; type=\"application/json\", ; rel=\"service-doc\"; type=\"text/html\"" } }, "Allow": { "schema": { "type": "string", "const": "POST" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./schemas/error-v1.schema.json" }, { "properties": { "error": { "properties": { "code": { "enum": [ "method_not_allowed" ] } } } } } ] }, "examples": { "method_not_allowed": { "value": { "schema_version": "sun-terminal.error@1", "error": { "code": "method_not_allowed", "message": "Use POST for one atomic consultation.", "retryable": false } } } } } } }, "409": { "description": "The key, immutable version, active recovery state, or terminal failed encounter prevents a successful response. Stable codes: encounter_failed, encounter_recovery_required, idempotency_conflict, idempotency_key_expired, instrument_version_unavailable.", "headers": { "Content-Type": { "required": true, "schema": { "type": "string", "const": "application/json; charset=utf-8" } }, "Cache-Control": { "required": true, "schema": { "type": "string", "const": "no-store" } }, "Link": { "required": true, "description": "Discover the OpenAPI service description and HTML service documentation.", "schema": { "type": "string", "const": "; rel=\"service-desc\"; type=\"application/json\", ; rel=\"service-doc\"; type=\"text/html\"" } }, "Retry-After": { "description": "Present with value 1 only for encounter_recovery_required. It is absent for encounter_failed and other non-retryable 409 errors.", "schema": { "type": "string", "const": "1" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./schemas/error-v1.schema.json" }, { "properties": { "error": { "properties": { "code": { "enum": [ "encounter_failed", "encounter_recovery_required", "idempotency_conflict", "idempotency_key_expired", "instrument_version_unavailable" ] } } } } } ] }, "examples": { "encounter_failed": { "value": { "schema_version": "sun-terminal.error@1", "error": { "code": "encounter_failed", "message": "This committed encounter could not be completed and will not be redrawn under this idempotency key.", "retryable": false } } }, "encounter_recovery_required": { "value": { "schema_version": "sun-terminal.error@1", "error": { "code": "encounter_recovery_required", "message": "The encounter is committed but not final. Retry the same request with the same idempotency key; no new draw will be created.", "retryable": true } } }, "idempotency_conflict": { "value": { "schema_version": "sun-terminal.error@1", "error": { "code": "idempotency_conflict", "message": "This idempotency key is already bound to different canonical input.", "retryable": false } } }, "idempotency_key_expired": { "value": { "schema_version": "sun-terminal.error@1", "error": { "code": "idempotency_key_expired", "message": "This idempotency key is outside the retry window. Do not create a replacement retry key.", "retryable": false } } }, "instrument_version_unavailable": { "value": { "schema_version": "sun-terminal.error@1", "error": { "code": "instrument_version_unavailable", "message": "The requested immutable instrument version is not available.", "retryable": false } } } } } } }, "413": { "description": "The request exceeds 8 KiB. Stable codes: payload_too_large.", "headers": { "Content-Type": { "required": true, "schema": { "type": "string", "const": "application/json; charset=utf-8" } }, "Cache-Control": { "required": true, "schema": { "type": "string", "const": "no-store" } }, "Link": { "required": true, "description": "Discover the OpenAPI service description and HTML service documentation.", "schema": { "type": "string", "const": "; rel=\"service-desc\"; type=\"application/json\", ; rel=\"service-doc\"; type=\"text/html\"" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./schemas/error-v1.schema.json" }, { "properties": { "error": { "properties": { "code": { "enum": [ "payload_too_large" ] } } } } } ] }, "examples": { "payload_too_large": { "value": { "schema_version": "sun-terminal.error@1", "error": { "code": "payload_too_large", "message": "The consultation request must not exceed 8 KiB.", "retryable": false } } } } } } }, "429": { "description": "The per-location anonymous attempt limit has been reached. Stable codes: rate_limited.", "headers": { "Content-Type": { "required": true, "schema": { "type": "string", "const": "application/json; charset=utf-8" } }, "Cache-Control": { "required": true, "schema": { "type": "string", "const": "no-store" } }, "Link": { "required": true, "description": "Discover the OpenAPI service description and HTML service documentation.", "schema": { "type": "string", "const": "; rel=\"service-desc\"; type=\"application/json\", ; rel=\"service-doc\"; type=\"text/html\"" } }, "Retry-After": { "required": true, "schema": { "type": "string", "const": "60" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./schemas/error-v1.schema.json" }, { "properties": { "error": { "properties": { "code": { "enum": [ "rate_limited" ] } } } } } ] }, "examples": { "rate_limited": { "value": { "schema_version": "sun-terminal.error@1", "error": { "code": "rate_limited", "message": "The anonymous consultation limit has been reached. Retry later with the same idempotency key.", "retryable": true } } } } } } }, "503": { "description": "A required gate, limiter, storage operation, or recovery path is unavailable. Stable codes: agent_door_unavailable, idempotency_commit_unknown, rate_limit_unavailable, service_unavailable.", "headers": { "Content-Type": { "required": true, "schema": { "type": "string", "const": "application/json; charset=utf-8" } }, "Cache-Control": { "required": true, "schema": { "type": "string", "const": "no-store" } }, "Link": { "required": true, "description": "Discover the OpenAPI service description and HTML service documentation.", "schema": { "type": "string", "const": "; rel=\"service-desc\"; type=\"application/json\", ; rel=\"service-doc\"; type=\"text/html\"" } }, "Retry-After": { "description": "Present with value 1 only for idempotency_commit_unknown. It is absent for other 503 errors.", "schema": { "type": "string", "const": "1" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./schemas/error-v1.schema.json" }, { "properties": { "error": { "properties": { "code": { "enum": [ "agent_door_unavailable", "idempotency_commit_unknown", "rate_limit_unavailable", "service_unavailable" ] } } } } } ] }, "examples": { "agent_door_unavailable": { "value": { "schema_version": "sun-terminal.error@1", "error": { "code": "agent_door_unavailable", "message": "The agent consultation door is not enabled.", "retryable": true } } }, "idempotency_commit_unknown": { "value": { "schema_version": "sun-terminal.error@1", "error": { "code": "idempotency_commit_unknown", "message": "The idempotency commit could not be confirmed. Retry only with the same idempotency key.", "retryable": true } } }, "rate_limit_unavailable": { "value": { "schema_version": "sun-terminal.error@1", "error": { "code": "rate_limit_unavailable", "message": "Anonymous consultation is unavailable because its rate limit is not active.", "retryable": true } } }, "service_unavailable": { "value": { "schema_version": "sun-terminal.error@1", "error": { "code": "service_unavailable", "message": "The consultation service is temporarily unavailable. Preserve the idempotency key and try again later.", "retryable": true } } } } } } } }, "x-sun-terminal-rate-limit": { "authentication": "anonymous", "attempts": 10, "periodSeconds": 60, "key": "connecting IP", "scope": "each Cloudflare location", "exactGlobalAccounting": false, "appliedBeforeBodyParsing": true, "missingBindingBehavior": "fail-closed" }, "x-sun-terminal-retention": { "activeRecordMilliseconds": 86400000, "cleanupSchedule": "17 * * * *", "cleanupFrequency": "hourly", "d1TimeTravel": "Cloudflare D1 Time Travel may retain recoverable database history after active-row deletion; duration depends on the platform plan and configuration.", "activeRecordFields": [ "idempotency-key digest and issue/expiry timestamps", "request fingerprint and canonical normalized input", "instrument and manifest identifiers", "encounter status, acquisition time, and pending ownership deadline", "final encounter id, exact response bytes, response hash, and final timestamp", "failed timestamp and one bounded internal failure classification" ], "failedRecordRetention": "Terminal failed records remain through the existing 24-hour active idempotency window and are removed by the same hourly cleanup policy.", "internalFailureMetadata": { "classificationCount": 2, "exceptionNamesOrMessagesStored": false, "subsystemCausesStored": false, "rawClassificationsExposedAsPublicErrorCodes": false } }, "x-sun-terminal-encounter-lifecycle": { "states": [ "pending", "final", "failed" ], "ownerLeaseMilliseconds": 30000, "timeoutEligibility": "At the ownership deadline, a pending row becomes eligible for a later matching request to conditionally record terminal failure; time passing alone does not run a background transition.", "failedStateTerminal": true, "failedStateRetryable": false, "failedStateRedrawn": false, "replacementConsultationCreatedOrRecommended": false, "publicFailureCode": "encounter_failed", "internalFailureClassificationCount": 2, "internalFailureDetailsPublic": false }, "x-sun-terminal-cors": { "crossOriginBrowserRequestsSupported": false, "accessControlResponseHeaders": [], "preflight": { "method": "OPTIONS", "status": 405, "errorCode": "method_not_allowed", "allowHeader": "POST" }, "explanation": "The operation sends no Access-Control-Allow-* headers. Browser requests from another origin cannot complete the required preflight; same-origin and non-browser clients are unaffected." } } } } }