# API reference Authenticated endpoints require `Authorization: Bearer` followed by the issued credential. JSON requests use `Content-Type: application/json`. The service rejects browser-origin requests. Credentials may also be sent in an `x-api-key` header. REST success responses are JSON; errors contain an `error` object with `code` and `message`. Input-validation messages do not reflect submitted values. ## Compatible endpoints `POST /v1/chat/completions` accepts an OpenAI Chat Completions request and `POST /v1/messages` accepts an Anthropic Messages request. Both require the `submit` and `read` scopes on the configured queue. `GET /v1/models` returns one model, `dot`. Each request becomes one task. Its payload is `{"messages": [...]}`, where every entry has a `role` and text `content`; an Anthropic `system` value becomes a leading system message. The task instructions ask the Dot to complete with `{"content": ""}`. A string result, or an object with a string `content`, `text`, or `output`, is used as the reply; any other result is returned as serialized JSON. | Aspect | Behavior | |---|---| | Content | Strings and `text` parts. Any other part type returns 400 `unsupported_content` | | `model` | Any string; echoed in the response | | Other request fields | Accepted and ignored, including sampling parameters, `max_tokens`, `n`, and `tools` | | Response `id` | The task ID, usable with `GET /v1/tasks/{task_id}` | | Usage | Always zero | | Conversation size | Bounded by the 128 KiB operation limit; larger requests return 413 | The response waits until the task is terminal. A completed task returns the reply with `finish_reason: stop` or `stop_reason: end_turn`. A failed, cancelled, or expired task returns 502 with the task error. After the completion timeout the response is 504 with code `timeout`; the task stays queued until its own deadline and the error object carries `task_id`. If the caller disconnects first, the task is cancelled. With `stream: true` the response is `text/event-stream`. OpenAI streams open with a role delta, send `: keepalive` comments while waiting, then one content delta, a finish chunk, and `data: [DONE]`. Anthropic streams send `message_start`, `content_block_start`, `ping` events while waiting, then one `content_block_delta` and the closing events. A failure after the stream has started is sent as an error event, because the status line is already 200. Errors use the dialect of the endpoint: `{"error": {"message", "type", "param", "code"}}` for OpenAI and `{"type": "error", "error": {"type", "message"}}` for Anthropic. The Responses API, token counting, embeddings, and tool calling are not implemented. ## HTTP routes | Method and path | Response | |---|---| | `POST /v1/chat/completions` | Chat completion or event stream | | `POST /v1/messages` | Message or event stream | | `GET /v1/models` | Model list | | `POST /v1/tasks` | `submit_task` response | | `GET /v1/tasks/{task_id}` | `get_task` response | | `POST /v1/tools/{name}` | Named operation response | | `GET /v1/capabilities` | Permitted tools, descriptions, and input JSON Schemas | | `POST /mcp` | JSON-RPC response or HTTP 202 for notifications | | `GET /healthz` | Process liveness | | `GET /readyz` | Storage and background-cycle readiness | Missing or invalid credentials return 401; forbidden operations return 403; inaccessible tasks return 404; invalid transitions return 409; malformed input returns 400 or 422; unsupported content type returns 415; oversized requests return 413; rate limits return 429 with `Retry-After`. Readiness failure returns 503. Liveness and readiness do not require credentials and expose no task data. ## Operations Input schemas are generated from the server validation models and exposed by discovery. Unknown input fields are rejected. Defaults and limits below apply when fields are omitted. | Operation | Scope | Parameters | |---|---|---| | `submit_task` | submit | Required `queue`, `instructions`, `idempotency_key`; optional JSON `payload`, `max_attempts` (3, range 1–20), `ttl_seconds` (86400, range 60–2592000) | | `get_task` | read | `task_id` | | `list_tasks` | read | `queue`; optional `status`, `after` (0), `limit` (50, range 1–100) | | `claim_task` | work | `task_id`; optional `lease_seconds` (600, range 30–3600) | | `heartbeat_task` | work | `task_id`, `lease_token`; optional `lease_seconds` (600, range 30–3600) | | `complete_task` | work | `task_id`, `lease_token`, JSON `result` | | `release_task` | work | `task_id`, `lease_token`, `error`; optional `retry` (true), `delay_seconds` (0, range 0–3600) | | `cancel_task` | submit | `task_id`, `reason` | Most responses contain `task`. Claim also returns `lease_token`; keep it confidential. Listing returns `tasks` and `next_cursor`. Pass the cursor as `after`; a null cursor ends the scan. Task timestamps are UTC ISO 8601 strings. Task records include sequence, queue, instructions, payload, status, result, error, attempt budget, revision, availability, deadline, and lease expiry. Identity and lease hashes are not exposed. ## MCP transport The server supports stateless JSON-RPC requests over HTTP with JSON responses. It implements `initialize`, `ping`, `tools/list`, and `tools/call`, plus `server/discover`, `events/list`, `events/subscribe`, and `events/unsubscribe`. Initialized notifications return 202. The supported initialization versions are listed in `protocol.py`; unsupported requested versions negotiate the server fallback. Discovery exposes Events protocol version `2026-07-28`. This transport does not provide SSE streams, session IDs, resources, prompts, batching, OAuth metadata, or a remote execution environment. Clients must support the implemented transport and authentication. A client supporting only ordinary MCP tools will need polling unless it also implements the Events extension. When explicitly enabled, `POST /mcp/{token}` accepts a credential in its path for connector compatibility. It has the same token permissions and expiry. This path is a secret and must be redacted throughout the ingress chain. ## Events extension Standard MCP request metadata (`params._meta`) is accepted independently of event arguments and is not persisted as subscription data. Events are `task.available` and `task.updated`. Subscription arguments contain `queue`. Delivery contains `mode` set to `webhook`, a public HTTPS `url` on port 443, and a `secret` in `whsec_` base64 format containing 24–64 decoded bytes. Every subscribe or renewal request requires the signing secret. Operations use the same principal, event name, queue, and URL to identify the subscription. `ttlMs` is optional; the service caps it at the configured subscription TTL. `cursor` must be null or omitted. The subscription response contains `id`, `refreshBefore`, `cursor: null`, and `truncated: false`. Renew before expiry. Unsubscribe uses the same identity fields; it does not require the signing secret. Callback verification sends a signed object containing `type: verification` and `challenge`. The destination must return a successful status and a JSON object with the same challenge. Event payloads contain `eventId`, `name`, `timestamp`, `data`, and `cursor`. Data contains `task_id`, `queue`, `status`, and `revision`. Signatures use Standard Webhooks headers `webhook-id`, `webhook-timestamp`, and `webhook-signature`. The HMAC-SHA256 input concatenates the message ID, timestamp, and exact body bytes separated by periods. Receivers must verify signatures and timestamp freshness and deduplicate event IDs. Rotation briefly signs with both current and previous keys for five minutes; keep both verification keys during transition. The extension contract follows the [OpenAI MCP Events specification](https://developers.openai.com/plugins/build/mcp-events). Compatibility with each host's provisioning and authentication flow must be verified separately. ## Python client `dot2api.client.Client` accepts a service base URL, bearer token, and request timeout. `call` invokes an operation with a parameter dictionary. `wait` polls a task until it reaches a terminal state or times out. The client requires HTTPS for non-loopback destinations and does not follow redirects. It does not automatically retry mutations after transport errors. `ClientError` exposes HTTP status and a sanitized error code.