HTTP API
aidy serves these routes under the host’s origin. The host reverse-proxies them, or mounts the handler when aidy is embedded. The protocol version string is aidy/0; the API prefix is /aidy/v0.
| Endpoint | Purpose |
|---|---|
POST /aidy/v0/threads |
Create a thread. |
GET /aidy/v0/threads?cursor= |
The user’s threads, newest first. |
GET /aidy/v0/threads/{id} |
The thread, its messages and its open interrupts. |
PATCH /aidy/v0/threads/{id} |
Rename a thread. |
DELETE /aidy/v0/threads/{id} |
Delete a thread. |
POST /aidy/v0/threads/{id}/runs |
Start a run; the response is that run’s events as SSE. |
GET /aidy/v0/threads/{id}/events?after={seq} |
Replay from seq, then follow live (SSE). |
PUT /aidy/v0/threads/{id}/messages/{messageId}/feedback |
Rate an assistant message. |
POST /aidy/v0/runs/{id}/cancel |
Cancel a run. |
GET /aidy/v0/info |
The assistant’s name, for the UI. |
GET /aidy/v0/catalog |
Operations visible to this user. |
GET /aidy/v0/search |
Federated search. |
GET, PUT, DELETE /aidy/v0/settings |
Model settings. PUT and DELETE need aidy:admin. |
GET /aidy/v0/feedback |
Every user’s feedback, for aidy:admin. |
POST /aidy/v0/tasks/{taskId} |
The host completes a deferred task. |
POST /aidy/v0/generate |
One model completion for a host job. |
/mcp |
MCP over streamable HTTP. |
GET /skill.md, GET /llms.txt |
Generated agent-facing documents. |
GET /.well-known/aidy-keys.json |
aidy’s public delegation keys. |
Authentication
Section titled “Authentication”Every request carries the user’s own credential: the Authorization header, the Cookie header, or both. aidy forwards them to the catalog’s role: identity operation to learn who the user is; see Identity. A thread belongs to one (subject, tenant), and another user’s thread answers 404.
POST /aidy/v0/tasks/{taskId} and POST /aidy/v0/generate are the exceptions: the host authenticates its own calls with an Aidy-Host-Assertion.
For POST, PUT, PATCH and DELETE:
- a request with
Sec-Fetch-Site: cross-siteis refused with403 cross_site; - under
/aidy/v0, a request with a body must sendContent-Type: application/json, and a request without aContent-Typemust have no body, otherwise415 unsupported_media_type. ADELETEor a cancel needs neither.
Together these keep other sites from acting as a cookie-authenticated user.
Errors
Section titled “Errors”Errors other than the SSE stream answer JSON:
{ "error": { "code": "not_found", "message": "No such thread." } }| Status | code |
When |
|---|---|---|
| 400 | invalid_request |
The body or a query parameter is invalid. |
| 401 | unauthorized |
The identity operation rejected the credential. On /mcp, with OAuth configured, WWW-Authenticate names the protected-resource metadata. |
| 401 | aidy_assertion_invalid |
A task completion or host job without a valid Aidy-Host-Assertion. |
| 403 | forbidden |
PUT or DELETE /settings, or GET /feedback, without aidy:admin. |
| 403 | cross_site |
A cross-site mutating request. |
| 404 | not_found |
No such thread, run or task for this user. |
| 404 | session_not_found |
An unknown MCP session. |
| 409 | run_active |
The thread already has an active run. |
| 409 | task_closed |
The task was completed or cancelled already. |
| 415 | unsupported_media_type |
A mutating request whose body is not application/json. |
| 422 | invalid_output |
A host job’s answer is not valid against its schema, after one repair attempt. |
| 500 | internal |
Anything else. |
| 503 | settings_unreadable |
Saved settings were sealed with a secret aidy no longer has. |
| 503 | model_unavailable |
A host job found no model endpoint that could answer. |
| 504 | timeout |
A host job ran past the run timeout. |
Run failures are reported inside the event stream as RUN_ERROR; see Events.
Threads
Section titled “Threads”POST /aidy/v0/threads
Section titled “POST /aidy/v0/threads”{ "title": "Optional title, at most 200 characters" }201:
{ "id": "th_…", "title": "", "createdAt": "2026-11-19T08:00:00.000Z" }GET /aidy/v0/threads?cursor=
Section titled “GET /aidy/v0/threads?cursor=”{ "items": [{ "id": "th_…", "title": "…", "createdAt": "…", "updatedAt": "…" }], "next": "<cursor>"}A page holds 20 threads. next is present when more threads follow; pass it as cursor.
GET /aidy/v0/threads/{id}
Section titled “GET /aidy/v0/threads/{id}”{ "id": "th_…", "title": "…", "createdAt": "…", "updatedAt": "…", "messages": [], "interrupts": []}messages is AG-UI Message[]. interrupts are the open interrupts, in the shapes of Interrupts.
PATCH /aidy/v0/threads/{id}
Section titled “PATCH /aidy/v0/threads/{id}”{ "title": "New title" }title is required, 1 to 200 characters after trimming. Answers the thread as in the list.
DELETE /aidy/v0/threads/{id}
Section titled “DELETE /aidy/v0/threads/{id}”204. The thread is deleted with its messages, events, runs, interrupts and tasks.
POST /aidy/v0/threads/{id}/runs
Section titled “POST /aidy/v0/threads/{id}/runs”The body is AG-UI RunAgentInput. aidy reads three fields:
{ "messages": [ { "id": "m_1", "role": "user", "content": [ { "type": "text", "text": "Why is this box slow?" }, { "type": "image", "source": { "type": "url", "value": "/files/shot.png", "mimeType": "image/png" }, "metadata": { "aidy": { "name": "shot.png" } } } ] } ], "context": [{ "description": "The page the user is on", "value": "/console/instance/vm-42" }], "resume": [ { "interruptId": "int_…", "status": "resolved", "payload": { "approved": true }, "metadata": { "aidy": { "argsHash": "q2…" } } } ]}- A user message’s
contentis text, or AG-UI content parts of typetext,imageanddocument, with at most 10 images and documents. Other parts answer400. How aidy gives them to the model is in AG-UI: user messages. context([{description, value}]) is what the user is looking at. aidy adds it to this run’s system prompt only, as information rather than instructions: at most 16 entries and 8000 characters of values, later entries cut first. It is not stored.- The server owns the history.
messagesmay repeat messages aidy already holds; only messages with new ids are appended. A changed earlier message fails the run withhistory_conflict. - A thread with open interrupts must answer every one of them in
resume[](statusisresolvedorcancelled), otherwise the run fails withopen_interrupts. A user who sends a new message instead sendscancelledfor each open interrupt alongside it.
The response is text/event-stream with the run’s events. Each event is one id: <seq> and one data: <AG-UI event JSON>; comment lines (: keepalive) keep the connection open. The stream ends after the run’s terminal event.
A run outlives its HTTP response. Closing the stream does not cancel it, so a confirmed write always finishes and is recorded. 409 run_active when the thread already has a running run.
GET /aidy/v0/threads/{id}/events?after={seq}
Section titled “GET /aidy/v0/threads/{id}/events?after={seq}”Replays events with a sequence number greater than after, then follows live, as SSE. Last-Event-ID takes precedence over after. The stream ends when the thread is idle. See sequence numbers.
POST /aidy/v0/runs/{id}/cancel
Section titled “POST /aidy/v0/runs/{id}/cancel”No body and no Content-Type are needed.
- A running run:
202 {"id": "run_…", "status": "cancelling"}. The run then finishes with outcomecancelled. - A finished run:
200 {"id": "run_…", "status": "<its status>"}.
Catalog
Section titled “Catalog”GET /aidy/v0/catalog
Section titled “GET /aidy/v0/catalog”The operations visible to this user, without role operations:
{ "operations": [ { "name": "stop_vm", "title": "Stop server", "description": "Stop a running cloud server (VM).", "effect": "update", "approval": "always", "surfaces": ["agent", "cli"], "input": { "type": "object", "properties": { "vm_id": { "type": "string" } }, "required": ["vm_id"] } } ]}input is the derived input schema.
Search
Section titled “Search”GET /aidy/v0/search
Section titled “GET /aidy/v0/search”| Parameter | Meaning |
|---|---|
q |
Required. The query; empty or missing answers 400. |
limit |
Hits to return. Default 10, at most 50. |
types |
Comma-separated hit types to keep (vm,doc). |
Every role: search operation and every configured source (such as knowledge) is queried in parallel, as the user, each with its own timeout: an operation’s x-aidy.timeoutSeconds (default 2, at most 10), a configured source’s timeoutMs (default 2000, at most 10 000). Hits are merged by reciprocal rank fusion (k = 60).
{ "hits": [ { "source": "search_vms", "type": "vm", "id": "vm-42", "title": "gpu-train-01", "excerpt": "Running · 8 × H100 · cn-beijing-a", "url": "/console/instance/vm-42", "updatedAt": "2026-11-19T08:00:00Z" } ], "failed": [{ "source": "search_chat", "code": "timeout" }]}A failed source is listed in failed with timeout, http_<status> or invalid_response; it never fails the whole search. Hits carry no content: that passage text goes only to the model. See Search.
Settings
Section titled “Settings”GET /aidy/v0/settings
Section titled “GET /aidy/v0/settings”Any signed-in user. API keys are never returned:
{ "models": { "chain": [ { "id": "primary", "provider": "openai-compatible", "model": "qwen-plus", "baseURL": "https://…", "hasApiKey": true } ] }}Entries also show vision, temperature, maxOutputTokens and cooldownSeconds when set. A model given in code as a custom LanguageModel shows as provider custom. When the saved settings were sealed with a secret aidy no longer has, every settings route answers 503 settings_unreadable.
PUT /aidy/v0/settings
Section titled “PUT /aidy/v0/settings”Needs the aidy:admin scope in the user’s identity, otherwise 403 forbidden. The body replaces the chain:
{ "models": { "chain": [ { "id": "primary", "provider": "openai-compatible", "model": "qwen-plus", "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1", "apiKey": "sk-…", "vision": false, "providerOptions": { "openai-compatible": { "enable_thinking": false } } } ] }}| Field | Meaning |
|---|---|
id |
Required, 1 to 64 characters, unique in the chain. |
provider |
openai-compatible, openai or anthropic. |
model |
Required model id. |
baseURL |
Optional URL. |
apiKey |
Optional. Omitted, the key of the entry with the same id is kept. Keys are sealed with AES-GCM at rest. |
vision |
Use this model for turns with images. |
temperature, maxOutputTokens |
Sent with every call to this endpoint. |
cooldownSeconds |
{quota?, rateLimit?, error?}: rest durations after a failure (default 6 h, 60 s, 5 min). |
providerOptions |
Passed to the provider, keyed by provider name. |
Models are tried in order. The chain replaces the configured one, custom models included. Answers the new settings as GET does. See Models.
Settings hold the model chain only; knowledge settings are not part of this API.
DELETE /aidy/v0/settings
Section titled “DELETE /aidy/v0/settings”Needs aidy:admin. Forgets the saved settings, so the configured chain applies again, and answers it as GET does.
GET /aidy/v0/info
Section titled “GET /aidy/v0/info”Any signed-in user:
{ "name": "Aidy" }name is the assistant’s display name (createAidy({ name }), AIDY_NAME). @aidy-dev/react shows it.
Feedback
Section titled “Feedback”PUT /aidy/v0/threads/{id}/messages/{messageId}/feedback
Section titled “PUT /aidy/v0/threads/{id}/messages/{messageId}/feedback”{ "rating": "down", "comment": "It stopped the wrong server." }rating is up or down; comment is optional, at most 2000 characters. A later rating of the same message replaces it. Answers the feedback item; 404 unless the message is an assistant message of the caller’s thread. Deleting the thread deletes its feedback.
GET /aidy/v0/feedback?since=&limit=&cursor=
Section titled “GET /aidy/v0/feedback?since=&limit=&cursor=”Needs aidy:admin. The feedback on threads of the caller’s tenant, oldest first:
{ "items": [ { "threadId": "th_…", "messageId": "msg_…", "rating": "down", "comment": "It stopped the wrong server.", "subject": "u_1", "createdAt": "2026-11-19T08:00:00.000Z" } ], "next": "<cursor>"}since is an RFC 3339 time; limit defaults to 50, at most 200. subject is the user who rated; createdAt is the time of the latest rating. next is the cursor of the following page.
Deferred tasks
Section titled “Deferred tasks”POST /aidy/v0/tasks/{taskId}
Section titled “POST /aidy/v0/tasks/{taskId}”An operation defers by answering 202 with {"aidyTask": "<id>"}; the run pauses with an aidy:task interrupt. The host completes the task later:
POST /aidy/v0/tasks/task_123Content-Type: application/jsonAidy-Host-Assertion: <compact JWS>
{"status": "succeeded", "result": {"id": "vm-43"}}| Field | Meaning |
|---|---|
status |
succeeded or failed. |
result |
Optional. On success it becomes the tool result, redacted as the operation says. |
The host assertion has op set to the operation that deferred, and sub (and ten) set to the task owner’s identity.
| Status | Body |
|---|---|
202 |
{"runId": "run_…"}: aidy started a run that resumes the interrupt. |
401 |
aidy_assertion_invalid: missing, invalid or replayed assertion, or no host keys configured. |
404 |
not_found: no such task. |
409 |
task_closed (completed or cancelled already) or run_active. |
The user may only resolve a task interrupt as cancelled.
Host jobs
Section titled “Host jobs”POST /aidy/v0/generate
Section titled “POST /aidy/v0/generate”One model completion for a job of the host’s, such as a scheduled report’s summary. Signed with a host assertion whose op is generate; sub and ten name whom the job is for.
POST /aidy/v0/generateContent-Type: application/jsonAidy-Host-Assertion: <compact JWS>
{ "instructions": "Write the weekly report's summary in two sentences.", "input": "Closed: 14 items. Opened: 9. Slowest: I-1647 (6 days).", "schema": { "type": "object", "properties": { "headline": { "type": "string" } }, "required": ["headline"] }, "maxOutputTokens": 400}| Field | Meaning |
|---|---|
input |
Required. The text to work on. |
instructions |
Optional system instructions. |
schema |
Optional JSON Schema. With it the answer is {object}, a value valid against the schema; without it, {text}. |
maxOutputTokens |
Optional; wins over the endpoint’s own. |
The call goes through the model chain, without tools or a thread, and is bounded by the run timeout. An answer that is not valid against schema is sent back to the same endpoint once, with what is wrong. See Host jobs.
| Status | Body |
|---|---|
200 |
{"text": "…"} or {"object": {…}}. |
400 |
invalid_request: an invalid body or schema. |
401 |
aidy_assertion_invalid. |
422 |
invalid_output: the second answer is still not valid. |
503 |
model_unavailable. |
504 |
timeout. |
Host assertions
Section titled “Host assertions”Aidy-Host-Assertion is an EdDSA JWS signed with a host key that aidy is configured with (hostKeys, AIDY_HOST_KEYS). Its header is the delegation assertion’s, {"alg": "EdDSA", "kid": "…", "typ": "aidy-call+jwt"}, and it has the claims of the delegation assertion, with these values:
issthe host’s origin,audaidy’s own URL;htmPOST;htuthe origin of aidy’s public URL followed by the path and query the host posts to, whatever internal address a proxy forwards it to;bshthe hash of this body;opthe deferred operation, orgenerate;sub(andten) whom the call is for;exp - iatat most 60 seconds; eachjtiis accepted once.
A failed check answers 401 aidy_assertion_invalid. A JavaScript host signs with signAssertion(claims, key) from @aidy-dev/spec/delegation; see Host jobs for an example. The Python kit has no signing helper: sign the compact JWS with any Ed25519 JWS library.
/mcp serves MCP over streamable HTTP with the user’s bearer credential. Tools are the catalog operations with the mcp surface, plus search. A write tool requires an MCP elicitation confirmation from the client; a client without elicitation sees the tool but its call is refused with an explanation. Each tool carries its CLI spelling in _meta.aidy ({command, args, effect}).
When mcp.authorizationServers is configured, aidy also serves GET /.well-known/oauth-protected-resource/mcp. See MCP clients.
Documents and keys
Section titled “Documents and keys”| Route | Content |
|---|---|
GET /skill.md |
text/markdown. The agent skill for the catalog the caller can see. Always 200: without a credential, from the OpenAPI document the host serves anonymously, or, when the host answers it 401/403, the guide and how to connect without the operations (remembered 5 minutes). GET /llms.txt works the same way. |
GET /llms.txt |
text/plain. The llmstxt.org file for the same catalog. |
GET /.well-known/aidy-keys.json |
{"keys": [{"kty": "OKP", "crv": "Ed25519", "x": "…", "kid": "…"}]}: aidy’s public signing key, for inspection. Hosts pin it in their configuration rather than fetching it. |