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.
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": "<reply>"}. 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.
| 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.
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.
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.
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. Compatibility with each host's provisioning and authentication flow must be verified separately.
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.