Auth and limits

Keys are planned, not available

The proposed API uses server-side API keys with organization ownership and scopes. There is no signup, key-creation page, or working test key at this stage.

X-API-Key: YOUR_SERVER_SIDE_API_KEY

Keep a future key on your server. Do not place it in browser JavaScript, a mobile binary, a public repository, or a shared URL. We intend to support rotation and revocation; the final lifecycle and operational procedures are not launched.

Permissions

The catalog operations require catalog:read; batched prices require prices:read; usage requires usage:read. An invalid or revoked key produces 401. A valid key without the required scope produces 403.

The key determines the organization. Clients do not select a different tenant by supplying an organization ID in the query or body. Intended quotas belong to the organization, so rotating a key does not create another allowance.

Rate limits and request allowances

The design separates a short-term request rate from a monthly allowance. A 429 response identifies which limit was reached. For a rate limit, respect Retry-After and use bounded retries with jitter. For an exhausted monthly allowance, inspect the usage response rather than immediately repeating the request.

No public subscription allowance, requests-per-minute promise, or commercial price has been finalized. Numbers inside synthetic usage examples illustrate the schema only.

Proposed metering semantics

The current draft counts a successful data request as one request credit, including empty catalog results, mixed missing-price batches, and internal cache hits. The usage operation, error responses, and valid idempotent batch replays are not charged.

The draft batch size is 1–50 distinct price selections, including mixed games and product kinds. A card selection includes its variant and condition; requesting two different conditions for the same card uses two positions in the batch. This request-credit model and its limits may change after we understand real integrations and data costs. They are not billing terms for an available service.

Retrying a batch

Idempotency-Key is required for the proposed batch operation. Within the 10-minute draft retention window, reuse the same key only for the same normalized request body. A successful replay returns the original data and snapshot; it does not fetch a new price.

A changed body under the same key produces 409. After retention expires, the request is new work. Use a new key for a new nightly job. Replays still require a valid key and are still rate limited.

See the batch reference for the key’s syntax and error reference for recovery guidance.