Production behavior
Design for retries, deadlines, and incomplete work.
The v1 API makes asynchronous work and failure states explicit. Clients remain responsible for deadlines, secret handling, and downstream review.
Idempotency
Create endpoints require Idempotency-Key. The same key and request replay the original result. Reusing a key with different intent is rejected.
Pagination
List and output-content reads use opaque cursors. Follow the returned next cursor without parsing or inventing it. Stop when no next cursor is returned.
Retries and rate limits
Retry bounded 429 and transient 5xx responses only when the method is safe or an idempotency key protects the create. Honor Retry-After and add jitter. Do not retry validation, authentication, or authorization failures.
Polling
Use Location and Retry-After from accepted responses, cap total attempts, and preserve the job ID across process restarts. Terminal status is authoritative.
Retention and deletion
Ephemeral, temporary, and account classes define lifecycle intent. Responses expose expiry when applicable. Deletion removes a terminal job and retained outputs through an accepted asynchronous operation.
Limits
Current registry limits direct text to 2,000,000 characters, files to 100 MiB each, and 20 files per job. Live capabilities are authoritative.
Errors
Errors use problem details with a stable code, human-readable detail, request ID, and relevant fields. Log the request ID, not the credential or private source.
Webhooks
Organization-scoped webhook endpoints support signed, replay-resistant terminal lifecycle events with bounded retries, delivery history, and dead-letter visibility. Polling remains the authoritative fallback.
Versioning
Stable routes begin with /v1. Additive fields may appear. Breaking changes require a new version and migration notice. Clients should ignore unknown response fields.