> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqwish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API behavior

> Authentication, limits, pagination and the difference between retryable errors and safe replay.

Start by checking what your account and deployment support:

```bash theme={null}
curl --fail-with-body https://console.sqwish.ai/v1/decisionone \
  -H "Authorization: Bearer $D1_API_KEY"
```

Read `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

Send `Authorization: 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 and `application/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.

| Boundary | Current contract |
| - | - |
| JSON body | Up to 1 MiB |
| Dataset JSONL upload | Up to 16 MiB and 20,000 rows |
| Labelling source | Up to 16 MiB and 2,000 rows |
| Decisions in a native request | 1–64 at schema level; the chosen model may allow fewer |
| Model input | Consult `max_prompt_tokens` and `max_questions` in `/v1/models` |

`/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:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "The request does not match the schema.",
    "retryable": false,
    "request_id": "req_example",
    "details": [{"path": ["body", "decisions"], "message": "Check this field.", "type": "example"}]
  }
}
```

This is an illustrative shape. Branch on `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.

| Situation | Response |
| - | - |
| `401` | Supply a valid key; recreate it if revoked. |
| `403` | Check account status and access. |
| `402` | Check account credit before sending more requests. |
| `413` / `422` | Correct the body or split the input. |
| `409` | Inspect resource state or an idempotency conflict. |
| `429` | Respect the returned retry guidance. |
| `5xx` / network timeout | Inspect retryability and the operation's replay contract. |

## Supported idempotency

The following **creation** operations accept `Idempotency-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](/examples/reliable-retries).

## Pagination

Resource lists with cursors return `data`, `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.