Skip to content

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.

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-site is refused with 403 cross_site;
  • under /aidy/v0, a request with a body must send Content-Type: application/json, and a request without a Content-Type must have no body, otherwise 415 unsupported_media_type. A DELETE or a cancel needs neither.

Together these keep other sites from acting as a cookie-authenticated user.

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.

{ "title": "Optional title, at most 200 characters" }

201:

{ "id": "th_…", "title": "", "createdAt": "2026-11-19T08:00:00.000Z" }
{
"items": [{ "id": "th_…", "title": "…", "createdAt": "…", "updatedAt": "…" }],
"next": "<cursor>"
}

A page holds 20 threads. next is present when more threads follow; pass it as cursor.

{
"id": "th_…",
"title": "…",
"createdAt": "…",
"updatedAt": "…",
"messages": [],
"interrupts": []
}

messages is AG-UI Message[]. interrupts are the open interrupts, in the shapes of Interrupts.

{ "title": "New title" }

title is required, 1 to 200 characters after trimming. Answers the thread as in the list.

204. The thread is deleted with its messages, events, runs, interrupts and tasks.

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 content is text, or AG-UI content parts of type text, image and document, with at most 10 images and documents. Other parts answer 400. 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. messages may repeat messages aidy already holds; only messages with new ids are appended. A changed earlier message fails the run with history_conflict.
  • A thread with open interrupts must answer every one of them in resume[] (status is resolved or cancelled), otherwise the run fails with open_interrupts. A user who sends a new message instead sends cancelled for 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.

No body and no Content-Type are needed.

  • A running run: 202 {"id": "run_…", "status": "cancelling"}. The run then finishes with outcome cancelled.
  • A finished run: 200 {"id": "run_…", "status": "<its status>"}.

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.

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.

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.

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.

Needs aidy:admin. Forgets the saved settings, so the configured chain applies again, and answers it as GET does.

Any signed-in user:

{ "name": "Aidy" }

name is the assistant’s display name (createAidy({ name }), AIDY_NAME). @aidy-dev/react shows it.

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.

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_123
Content-Type: application/json
Aidy-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.

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/generate
Content-Type: application/json
Aidy-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.

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:

  • iss the host’s origin, aud aidy’s own URL;
  • htm POST; htu the origin of aidy’s public URL followed by the path and query the host posts to, whatever internal address a proxy forwards it to; bsh the hash of this body;
  • op the deferred operation, or generate; sub (and ten) whom the call is for;
  • exp - iat at most 60 seconds; each jti is 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.

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.