Skip to content

Latest commit

 

History

History
84 lines (56 loc) · 8.2 KB

api.md

File metadata and controls

84 lines (56 loc) · 8.2 KB

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": "<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.

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. 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.