# Sun Terminal

> Divination instruments for humans and agents.

[Sun Terminal](https://sunterminal.net/) is a public threshold for divination instruments. Its visual entrance and Rider–Waite Tarot consultation are live.

## Rider–Waite Tarot

- Instrument ID: tarot.rider-waite
- Instrument version: 1
- Lifecycle: live
- Public description: [Rider–Waite Tarot instrument](https://sunterminal.net/instruments/tarot-rider-waite)
- Public consultation: `POST` [https://sunterminal.net/api/v1/consult](https://sunterminal.net/api/v1/consult)

Send Content-Type: application/json and an Idempotency-Key containing a fresh lowercase UUIDv7. No authentication is required. The body is limited to 8192 bytes, query parameters and unknown fields are rejected, count defaults to 1 and may be 1 through 78, and optional position labels must be the exact ordered generic sequence position-1 through position-N.

Retrying identical canonical input with the same key returns the exact stored response bytes and consumes no new entropy. Changing canonical input under that key returns HTTP 409 idempotency_conflict. Preserve the same key after an uncertain commit.

A newly acquired pending encounter has a 30-second ownership lease. Reaching the deadline makes its row eligible for a later matching request with the same canonical input and idempotency key to conditionally record terminal failure; it does not itself change durable state, and time passing alone does not run a background transition.

Retry-After: 1 is used for HTTP 409 encounter_recovery_required while the pending owner is active or HTTP 503 idempotency_commit_unknown when durable state cannot be confirmed. It is not used for terminal encounter_failed responses. A failed encounter is terminal and returns HTTP 409 encounter_failed with retryable set to false and no Retry-After header. It will not be redrawn under that idempotency key, and Sun Terminal does not create or recommend a replacement consultation.

Question text has no request field. It is not accepted, stored, logged, hashed or sent to another provider. The result contains card identities and upright or reversed orientations, without meanings or interpretation; interpretation belongs to the caller.

The anonymous limit is 10 attempts per 60 seconds per connecting IP at each Cloudflare location, not exact global accounting. A failed D1 row stores a failure timestamp and one of two bounded internal failure classifications through the existing 24-hour active idempotency window. It stores no exception details, and the internal classifications are not public error codes. Active D1 encounter 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 platform plan and configuration.

## Sun Oracle

- Lifecycle: parked
- Public consultation: unavailable

Sun Oracle is unfinished and parked by owner decision. It is not available and has no announced release date.

## Contract and examples

- [OpenAPI 3.1 service description](https://sunterminal.net/openapi.json)
- [Consultation request schema v1](https://sunterminal.net/schemas/consult-request-v1.schema.json)
- [Consultation response schema v1](https://sunterminal.net/schemas/consult-response-v1.schema.json)
- [Stable error schema v1](https://sunterminal.net/schemas/error-v1.schema.json)
- [Encounter receipt schema v1](https://sunterminal.net/schemas/encounter-receipt-v1.schema.json)
- [Minimal one-card request](https://sunterminal.net/examples/consult-request-v1.json)
- [Bounded three-card request](https://sunterminal.net/examples/consult-request-three-card-v1.json)
- [Illustrative success response](https://sunterminal.net/examples/consult-response-v1.json)
- [Idempotency conflict example](https://sunterminal.net/examples/idempotency-conflict-v1.json)
- [Node.js consultation example](https://sunterminal.net/examples/consult-node-v1.mjs)

## Public corpus and discovery

- [Developer reference](https://sunterminal.net/developers/tarot-rider-waite)
- [Rider–Waite v1 card identity catalogue](https://sunterminal.net/decks/rider-waite-v1.json)
- [Readable Rider–Waite card identities](https://sunterminal.net/decks/rider-waite)
- [About Sun Terminal](https://sunterminal.net/about)
- [Privacy and retention](https://sunterminal.net/privacy)
- [Crawler and training policy](https://sunterminal.net/robots.txt)
- [Canonical HTML sitemap](https://sunterminal.net/sitemap.xml)