training_available, labeling_available, prompt_tuning, models and limits before starting a workflow. Availability can change; an entry in the catalogue is not a promise that it can serve requests now.
Authentication
SendAuthorization: Bearer <key> over HTTPS. Keys belong to an account and should stay out of browser bundles and source control. An active account is required for most operations. Waitlisted accounts can read /v1/account and /v1/models, and request early access.
The public exceptions are /healthz, /v1/recipes, /v1/lint, /v1/systemone/translate and /v1/playground/decide. The first four run no decision inference. Anonymous playground inference is separately rate limited, accepts at most eight decisions, and refuses store: true. It may be disabled.
Requests and limits
Use JSON for ordinary operations andapplication/x-ndjson for raw JSONL uploads. Unknown request fields, duplicate JSON keys and invalid numeric values can be rejected. Keep outcome order stable: it is part of how a decision is presented to the model.
/v1/account reports effective request/minute, billed-token/minute and concurrent-operation limits, plus separate read and estimate-token budgets. Authenticated reads and existing-operation replay attempts consume the read budget, including pending or conflicting replays. Deployment ingress limits apply across dynamic routes before expensive processing. Limits return 429 with Retry-After; unavailable limiter storage returns 503. Security recovery and disabling automatic top-ups remain independent of account compute/read budgets.
A schema-valid request can still exceed a model’s serving limit. Split oversized requests or contexts before retrying. Model scoring can include prompt formatting beyond your own text; billed input tokens are a separate measure.
Errors and retries
Errors use one envelope:code, inspect details for validation failures, and keep the request ID. retryable means a later attempt may succeed. It does not mean an earlier attempt did no work. Respect Retry-After when returned and use bounded backoff with jitter.
Supported idempotency
The following creation operations acceptIdempotency-Key: datasets (JSON and JSONL), fine-tuning jobs, labelling sources and jobs, labelling finalization, prompt-tuning jobs, and named-model feedback datasets. The API reference shows the header only where supported.
Generate a key once per intended operation and persist it with the request. Retry the same operation with that key and unchanged input. The server returns the existing resource; changed input with the same key is a conflict. Replaying a job creation returns its current state, not necessarily its original queued representation. For raw uploads, keep the exact bytes and name.
Inference (/v1/decide, /v1/systemone and the Claude Code hook) also supports Idempotency-Key. Acceptance freezes model versions, fallback choices, tokenizer and tariffs. A successful response is committed with its settlement before it is returned and retained for 24 hours. Replays return the original outcome without running or charging again. Changed input conflicts; after response expiry the identity remains and the key returns idempotency_response_expired. Pending operations return request_in_progress with retry guidance. Replaying a failed operation returns that failure, not a new attempt.
Checkout creation and saved-card setup require an idempotency key. Automatic top-up settings use If-Match revisions to protect consent from stale updates. Creating API keys, promoting or rolling back versions has no general idempotency-key contract; consult state before repeating these mutations. See reliable retries.
Pagination
Resource lists with cursors returndata, has_more and next_cursor. Pass next_cursor as cursor on the next request, preserving filters. Stop when has_more is false. Model and recipe catalogues return complete object: "list" lists instead.
Dataset rows and held-out records use offset, limit, total and has_more. Labelling results use offset, limit and total; advance the offset by the number of rows returned. Job events return a data list in event order.
Live API controls
The API Reference uses the same production base URL as these examples, through Mintlify’s proxy. It describes customer operations only. The service’s own/openapi.json also retains its full operational reference.