Getting started

Wiki home · Practical examples · Complete endpoint index · OpenAPI schema

Base URL and authentication

All versioned requests use https://api.chaosdraft.com/v1 and HTTPS. Send the key as an Authorization bearer token. Keep it on your server, outside browser HTML, JavaScript, logs, and repositories.

curl -sS https://api.chaosdraft.com/v1/ai/access \
  -H "Authorization: Bearer $CHAOSDRAFT_API_KEY"

This is a practical first check for a key with ask_ai scope. It returns its active status and message allowance without consuming an AI message. The first-party * key can call the factual and deck routes shown elsewhere in this wiki. An ordinary customer key cannot use an unlisted scope just because the endpoint is documented.

Keys have independent activation/expiry, request rate and message limits. GET /v1/ai/access reports key-level allowance, not a consumer subscription tier. A scoped key currently allows one in-flight ASK request; another concurrent ask returns 429 ai_request_in_progress. A 429 rate_limited response may include Retry-After. Ask the platform operator for any scope you need; a key cannot expand its own access.

Acting for an end user

For permitted ASK subject routes, an active customer-owned api key may send X-End-User-Ref with its own stable opaque end-user ID. The API isolates data by customer and ref. Never use an email address, share a ref across people, or let a browser select the header. A missing header uses the key's own default user; it cannot access conversations created under a named ref. Demo or unowned keys cannot send this header. GET /v1/ai/feedback is customer-wide and does not accept it.

Response shape

Most successful JSON responses contain data and meta. The meta object includes request_id and often request_time, as_of, sources, coverage and/or pagination information appropriate to the route. Follow the exact schema for each operation in OpenAPI. Factual responses may carry verified_fact, statistical_result or AI-analysis labels; do not present an AI inference as a verified database fact.

{
  "data": {},
  "meta": {
    "request_id": "<request ID>"
  }
}

The example shows only the shared envelope, not a particular route's full response. Errors are JSON with error.type, error.code, error.message, error.request_id and error.details. Keep request_id when reporting a problem. Typical statuses are 400 for invalid input; 401 for a missing/invalid/revoked key; 403 for insufficient scope or policy; 404 for an unavailable resource; 409 for a conflict; 413/415 for image size/type; 429 for rate or concurrency limits; and 503 for temporary unavailability. Consult a route's OpenAPI responses rather than assuming every route has the same set.

Dates, pages, coverage and attribution

Many factual routes accept as_of=YYYY-MM-DD. It is the date for the requested fact, not necessarily today's data. Check the response's coverage and warnings: an unknown or uncovered legality is not legal, and a stored price is not a live checkout quote.

Pagination varies by family. Cards/sets and several event routes use an opaque cursor; rules/rulings and some format events use limit/offset; ASK conversations use an opaque list cursor and numeric before_turn/after_turn for turn history. Repeat the same filters and end-user identity on the next page. Do not parse an opaque cursor or assume every GET has one.

Every visible source-derived result must honor its response policy and attribution. Look at meta.sources and per-row provenance where requested. Scryfall, Wizards, local event suppliers and Card Kingdom fields may have different permissions. A granted API scope is not a grant to redistribute an entire source dataset. Some commercial channels currently deny fields or whole operations, so test access with your own key.

API versioning

Keep /v1 in the path and accept additional response fields. Generate types from openapi/v1.yaml. The contract lists the complete set of current operations and field-level validation; this wiki explains their use.