Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

Two ways to use a Bot from another app: the Bot URL you paste into it, and the compatible APIs that answer as the Bot. The Bot itself is on the Bots page.

In the Hub, open Bots, select the Bot, then open Link and keys. In Addresses, copy the OpenAI-compatible, Anthropic-compatible or MCP address, or open its row menu and choose How to use the OpenAI-compatible address, How to use the Anthropic-compatible address, or How to use the MCP address for a client example.

Every Bot has a per-realm URL ready to paste as the base URL of an OpenAI client, an Anthropic client, or an MCP client. realm is global or a 24-hex realm id; the short form …/bots/{bot}/… uses the agent’s current realm instead, and a Bot whose id is global or 24 hex is reached by the long form only. GET /api/v1/agent/bots/{id} lists a Bot’s URLs under urls. The path is read forgivingly: repeated slashes, a trailing slash, a missing or doubled /v1, and a whole …/chat/completions or …/messages URL pasted as the base all reach the same Bot. The Authorization and x-api-key headers are ignored: apps may send any value, and access is decided before the request reaches the agent.

The MCP server is stateless: it keeps no session and no ongoing Bot-update stream. POST each request. Use …/events on the Bot’s public host for live updates. There is no session to end: a DELETE of the base URL or /mcp answers 405 (Allow: POST), and a DELETE of any other door is 404. A GET of /mcp with Accept: text/event-stream answers 405 (Allow: POST).

Only the last message is read, and it must be a user message with text only (an image, audio or file part is refused 400). System messages (and, on …/chat/completions and …/responses, developer messages) count as the system prompt wherever they sit, so a trailing one is passed over when the last message is found. Text blocks of the last message that consist only of a client’s <system-reminder> note count as the system prompt too and are not posted; a last message of such notes only is refused 400. A side request an app makes on the model (a conversation title, a summary, follow-up suggestions, tags, or an autocompletion: never one that sends tools; recognised when its system prompt or last message starts with a chat app’s default prompt for that task, such as Open WebUI’s task prompts or LibreChat’s title prompt, when it matches Claude Code’s session-title request, or when its output budget (max_tokens, max_completion_tokens or max_output_tokens) is 64 or less) is not posted. Any other wording, including the user’s own request for a summary or a title, is a message to the Bot. The Bot’s model answers a side request in one completion, outside the Bot’s history, with at most 1024 output tokens, or the request’s own budget when that is lower. A Bot whose model cannot limit its output this way answers side requests with 502 upstream_error and never runs them uncapped.

A request that sends tools is not a side request, but this exclusion does not bypass request validation. An output budget that is not a positive integer is refused with 400, and so is a tool_choice that forces a tool. Otherwise, system prompts, client tools, sampling settings and output budgets are ignored. A streamed answer uses Server-Sent Events for the same reply.

When the reply started delegates, the Bot’s async and wait_seconds settings (PATCH /api/v1/agent/bots/{id}) say how the answer waits. With async false, the default, it waits up to wait_seconds more (15 until changed) and ends early once every delegate the reply started has asked for an approval or an answer, reported, closed, or finished its first tool call without asking; when one asked, the answer ends with what the Bot said about it. With async true the answer comes at once. Either way, what a delegate asks or reports later comes with the next answer.

A request sent again with the same messages (and the same user field, or Anthropic metadata.user_id) within 2 minutes, while its answer was never delivered in full, gets that answer without posting again. An Idempotency-Key header names the message instead: the same key gets the same answer while the Bot still holds its record (about 24 hours); after that it can post again, so check status or updates before resending. The same key with other content is refused 422 idempotency_key_reused on these agent URLs, or 409 request_conflict through the Bot’s public host. A non-streamed request waits up to 100 seconds for the reply; a streamed one sends keepalives and waits up to 10 minutes. The Bot is one conversation shared by every app that talks to it.

Reached through its Bot URL (the Bot’s public host), a Bot serves a GET of the host’s root (the Bot’s chat page, or its text guide for curl, agents, an empty User-Agent or ?view=text) and of …/SKILL.md without a key; called with one of its Bot URL keys, it serves …/v1, …/v1/models, …/v1/models/<model>, GET …/v1/key (that key’s name and holder note), …/v1/chat/completions, …/v1/responses, …/v1/messages, …/mcp and GET …/events (the Bot’s live events, as Server-Sent Events). Any other path is 404 path_not_allowed, and a listed path with another method is 405 method_not_allowed. There every error carries its code in X-Hoody-Error-Code (upper case) with a fixed message: bot_disabled, path_not_allowed, method_not_allowed, rate_limited, concurrency_limit, invalid_request, request_not_found, request_conflict, forbidden, upstream_error or internal_error; only a 429 carries Retry-After. Idempotency keys, the keys derived from a conversation and MCP refs belong to the calling key: the same Idempotency-Key under another key names another message, and a ref is unknown to any other key.

Through a Bot URL, the answer to your own message names its rows in the Bot’s shared log in a top-level hoody object on a chat completion, Responses response or Anthropic message. message_seq is the seq of the row your message wrote; reply_seq is the seq of the last row of its reply, where a spoken reply’s audio belongs. For streamed answers, hoody is on the chunk that carries the answer, on the response in response.completed, or on message_delta, respectively. MCP ask, answer and ask_audio return the same two fields in structuredContent.

Each field is left out while unknown or when there is no such row: a reply still working or cut by a reset can have message_seq without reply_seq. These values name rows, as shown by updates items and /events row frames; they are not cursors or resume positions. The same idempotency key or ref returns the same known values. Only your own answer carries this correlation; updates and /events do not.

A GET of …/events (through a Bot URL only; it takes no body) is a Server-Sent Events stream of what the MCP status and updates tools return: a status frame first and whenever the status changes (the status tool’s structured content), a row frame for each log row with a public form (the updates item; id: its seq), a cursor frame {seq} when rows without one moved the position, and at the end of the catch-up of a stream opened without Last-Event-ID (id: that seq), a gap or archived frame {next_seq} when the log no longer holds the rows after the position or was archived (id: next_seq - 1, possibly 0: the position moves back), a heartbeat comment every 15 s, and end {reason: reconnect} shortly before the stream’s 25 s lifetime ends or when the Bot restarts. After the response started, a failure is an error frame {code, message} and the stream closes. The first bytes set retry: 1000. Resume with the Last-Event-ID header (the resume position, which an EventSource keeps by itself): absent or blank, the stream starts at the 20 newest rows; 0, at the oldest row kept; any other value must be decimal digits, at most 16 of them, up to 2^53-1 (else 400 invalid_request). At most 4 streams are open per key, 32 per Bot and 16 per caller address; another is refused 429 concurrency_limit.

A GET of the Bot URL answers a short text page that starts with This is the URL of Bot <name> (bot:<realm>/<id>) and says what to paste where. Model doors (/v1/models) return the one-model list in the client format. A GET of /mcp with Accept: text/event-stream answers 405 (Allow: POST).

NameInTypeRequiredDescription
realmpathstringYesThe realm.
botpathstringYesThe bot.
Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief" \
-H "Authorization: Bearer <token>"

200 (help page, text/plain)

Media type: application/json, text/plain

This is the URL of Bot Chief (bot:global/chief).
Paste <base>/v1 as the base URL of an OpenAI client (chat completions, responses, models).
Paste <base> as the base URL of an Anthropic client (Messages, models).
Paste <base>/mcp into an MCP client.

The base URL answers this help page. A GET of a model door returns the one-model list, or the model, as application/json in the client’s format.

400

Media type: application/json

{
"code": "bad_request",
"message": "invalid request"
}

403

Media type: application/json

{
"code": "forbidden",
"message": "Hoody Kit programs are reached through their URLs only"
}

404

Media type: application/json

{
"code": "not_found",
"message": "resource not found"
}

405

Media type: application/json

{
"code": "method_not_allowed",
"message": "this MCP server sends no stream and keeps no session: POST each request"
}

409

Media type: application/json

{
"code": "realm_blocked",
"message": "realm is blocked"
}

429

Media type: application/json

{
"code": "rate_limited",
"message": "request rate limit exceeded"
}

500

Media type: application/json

{
"code": "internal_error",
"message": "internal server error"
}

503

Media type: application/json

{
"code": "service_unavailable",
"message": "service unavailable"
}
Error CodeTitleDescriptionResolution
bad_requestBad requestThe request was malformed or carried invalid parameters.Correct the request body or query parameters.
realm_scope_unsupportedRealm scope unsupportedA per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm.Omit the header, or name the realm the agent is pinned to.
invalid_realmInvalid realm selectorThe realm selector is malformed (not ""/"global"/a 24-hex id).Pass a valid realm selector.
forbiddenForbidden (Source IP Guard)Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.Call the agent through its URL, for example with hoody agent ….
not_foundNot foundThe requested resource does not exist.Verify the path and identifier.
method_not_allowedMethod not allowedThe MCP server keeps no session and no ongoing Bot-update stream; use …/events for live updates; a standalone GET event stream gets 405. The answer carries Allow: POST.POST each MCP request.
realm_blockedRealm blockedThe requested realm is blocked or corrupt; the request fails closed before dispatch.Select a valid, reachable realm.
bot_owned_elsewhereBot served by another agentAnother agent process on this machine serves the Bot (details.reason held), or its owner lock cannot be taken on this filesystem (details.reason lock_unavailable). Nothing of the Bot was read or changed. The answer carries Retry-After: 5. details.owner names the serving process (pid, started_at) when known, else null.Retry after Retry-After seconds, or reach the Bot through the agent that serves it. The Bot list includes such a Bot as a row with owned_elsewhere: true.
rate_limitedToo many requestsThe per-client request rate limit was exceeded; the gateway throttled the request before dispatch.Honor the Retry-After header and retry; reduce the request rate.
internal_errorInternal errorAn unexpected error occurred while handling the request.Retry; if persistent, inspect the daemon logs.
service_unavailableService unavailableThe daemon could not service the request because it was too busy, or a per-client stream concurrency cap was hit.Honor Retry-After and retry.
restriction_unknownLogin restriction unknownThe agent cannot read yet which realms its login may serve (GET /api/v1/agent/hoody/auth/status reports restriction unknown), so it refuses realm-scoped requests until it can. Nothing was read or changed.Retry after the restriction is readable.

GET /api/v1/agent/bots/{realm}/{bot}/{door}

Section titled “GET /api/v1/agent/bots/{realm}/{bot}/{door}”

A GET of a Bot door returns the help page (text/plain) on the base URL, the MCP URL, or a chat URL; returns the one-model list (application/json) on a model door; and answers 405 (Allow: POST) on /mcp with Accept: text/event-stream. Through a Bot URL, …/events answers text/event-stream: the live status and updates stream described above. An unknown Bot, and a realm this login does not serve, answer the same 404.

NameInTypeRequiredDescription
realmpathstringYesThe realm.
botpathstringYesThe bot.
doorpathstringYesThe door.
takeoverquerybooleanNo…/v1/realtime only: true takes over from the connection that controls the Bot’s voice now.
Last-Event-IDheaderstringNo…/events through a Bot URL only: the resume position (decimal digits, at most 16 of them, up to 2^53-1; 0 is the oldest row kept). Absent or blank, the stream starts at the 20 newest rows.
Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief/mcp" \
-H "Authorization: Bearer <token>"

200 (help page, text/plain)

Media type: application/json, text/plain, text/event-stream

This is the URL of Bot Chief (bot:global/chief).
Paste <base>/v1 as the base URL of an OpenAI client (chat completions, responses, models).
Paste <base> as the base URL of an Anthropic client (Messages, models).
Paste <base>/mcp into an MCP client.

The help page above is what the base URL, the MCP URL (as in this example) and a chat URL return. A GET of a model door returns the one-model list, or the model, as application/json in the client’s format; the one model’s id is the Bot’s id and its name is the Bot’s name.

400

Media type: application/json

{
"code": "bad_request",
"message": "invalid request"
}

403

Media type: application/json

{
"code": "forbidden",
"message": "Hoody Kit programs are reached through their URLs only"
}

404

Media type: application/json

{
"code": "not_found",
"message": "resource not found"
}

405

Media type: application/json

{
"code": "method_not_allowed",
"message": "this MCP server sends no stream and keeps no session: POST each request"
}

409

Media type: application/json

{
"code": "realm_blocked",
"message": "realm is blocked"
}

429

Media type: application/json

{
"code": "rate_limited",
"message": "request rate limit exceeded"
}

500

Media type: application/json

{
"code": "internal_error",
"message": "internal server error"
}

503

Media type: application/json

{
"code": "service_unavailable",
"message": "service unavailable"
}
Error CodeTitleDescriptionResolution
bad_requestBad requestThe request was malformed or carried invalid parameters.Correct the request body or query parameters.
realm_scope_unsupportedRealm scope unsupportedA per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm.Omit the header, or name the realm the agent is pinned to.
invalid_realmInvalid realm selectorThe realm selector is malformed (not ""/"global"/a 24-hex id).Pass a valid realm selector.
forbiddenForbidden (Source IP Guard)Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.Call the agent through its URL, for example with hoody agent ….
not_foundNot foundThe requested resource does not exist.Verify the path and identifier.
method_not_allowedMethod not allowedThe MCP server keeps no session and no ongoing Bot-update stream; use …/events for live updates; a standalone GET event stream gets 405. The answer carries Allow: POST.POST each MCP request.
realm_blockedRealm blockedThe requested realm is blocked or corrupt; the request fails closed before dispatch.Select a valid, reachable realm.
voice_busyVoice busyAnother connection controls this Bot’s voice.Close the other connection, or connect with takeover=true to take over from it.
bot_owned_elsewhereBot served by another agentAnother agent process on this machine serves the Bot (details.reason held), or its owner lock cannot be taken on this filesystem (details.reason lock_unavailable). Nothing of the Bot was read or changed. The answer carries Retry-After: 5. details.owner names the serving process (pid, started_at) when known, else null.Retry after Retry-After seconds, or reach the Bot through the agent that serves it. The Bot list includes such a Bot as a row with owned_elsewhere: true.
rate_limitedToo many requestsThe per-client request rate limit was exceeded; the gateway throttled the request before dispatch.Honor the Retry-After header and retry; reduce the request rate.
internal_errorInternal errorAn unexpected error occurred while handling the request.Retry; if persistent, inspect the daemon logs.
service_unavailableService unavailableThe daemon could not service the request because it was too busy, or a per-client stream concurrency cap was hit.Honor Retry-After and retry.
restriction_unknownLogin restriction unknownThe agent cannot read yet which realms its login may serve (GET /api/v1/agent/hoody/auth/status reports restriction unknown), so it refuses realm-scoped requests until it can. Nothing was read or changed.Retry after the restriction is readable.

A POST of the base URL reaches the Bot’s MCP server, the same as a POST of /mcp: an MCP client given the base URL reaches the Bot’s MCP server. OpenAI and Anthropic clients post to a door under the base URL (/v1/chat/completions, /v1/responses, /v1/messages; see the next route). The MCP server keeps no session and no ongoing Bot-update stream: POST each request, and use …/events on the Bot’s public host for live updates. The Authorization and x-api-key headers are ignored: apps may send any value, and access is decided before the request reaches the agent.

NameInTypeRequiredDescription
realmpathstringYesThe realm.
botpathstringYesThe bot.

An MCP JSON-RPC message. A POST of the Bot URL itself is its MCP door, using Streamable HTTP. Send Accept: application/json, text/event-stream.

NameTypeRequiredDescription
jsonrpcstringYesAlways 2.0.
idinteger | stringNoThe request id. It is absent on a notification.
methodstringYesThe MCP method, for example initialize, tools/list, tools/call or ping.
paramsobjectNoThe method’s parameters.
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
--data '{"jsonrpc":"2.0","id":1,"method":"ping","params":{}}'

200

Media type: application/json, text/event-stream

{
"jsonrpc": "2.0",
"id": 1,
"result": {}
}

The base URL answers an MCP reply (JSON-RPC 2.0) as application/json. Chat answers, including a chat completion, a Responses response or an Anthropic message, and Server-Sent Events come from the chat doors on the next route.

400

Media type: application/json

{
"code": "bad_request",
"message": "invalid request"
}

403

Media type: application/json

{
"code": "forbidden",
"message": "Hoody Kit programs are reached through their URLs only"
}

404

Media type: application/json

{
"code": "not_found",
"message": "resource not found"
}

409

Media type: application/json

{
"code": "realm_blocked",
"message": "realm is blocked"
}

413

Media type: application/json

{
"code": "payload_too_large",
"message": "request body exceeds the configured size limit"
}

422

Media type: application/json

{
"code": "idempotency_key_reused",
"message": "this Idempotency-Key was used for a different message"
}

429

Media type: application/json

{
"code": "rate_limited",
"message": "request rate limit exceeded"
}

500

Media type: application/json

{
"code": "internal_error",
"message": "internal server error"
}

503

Media type: application/json

{
"code": "service_unavailable",
"message": "service unavailable"
}
Error CodeTitleDescriptionResolution
bad_requestBad requestThe request was malformed or carried invalid parameters.Correct the request body or query parameters.
realm_scope_unsupportedRealm scope unsupportedA per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm.Omit the header, or name the realm the agent is pinned to.
invalid_realmInvalid realm selectorThe realm selector is malformed (not ""/"global"/a 24-hex id).Pass a valid realm selector.
forbiddenForbidden (Source IP Guard)Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.Call the agent through its URL, for example with hoody agent ….
not_foundNot foundThe requested resource does not exist.Verify the path and identifier.
realm_blockedRealm blockedThe requested realm is blocked or corrupt; the request fails closed before dispatch.Select a valid, reachable realm.
bot_owned_elsewhereBot served by another agentAnother agent process on this machine serves the Bot (details.reason held), or its owner lock cannot be taken on this filesystem (details.reason lock_unavailable). Nothing of the Bot was read or changed. The answer carries Retry-After: 5. details.owner names the serving process (pid, started_at) when known, else null.Retry after Retry-After seconds, or reach the Bot through the agent that serves it. The Bot list includes such a Bot as a row with owned_elsewhere: true.
payload_too_largePayload too largeThe request body exceeds the configured size limit (default 8 MiB). Reduce the request body.Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.
idempotency_key_reusedIdempotency key reusedThe Idempotency-Key already accepted a different message for this Bot.Use a fresh Idempotency-Key for a different message, or resend the identical message to get its answer.
rate_limitedToo many requestsThe per-client request rate limit was exceeded; the gateway throttled the request before dispatch.Honor the Retry-After header and retry; reduce the request rate.
idempotency_keys_exhaustedToo many remembered keysThe Bot already remembers 4096 Idempotency-Key values, each while its message is queued and for at least 24 hours after the message was accepted. Nothing was queued.Send the message later, when older keys have expired, or send it without an Idempotency-Key.
bot_busyBot busyThe Bot was answering other requests for the whole wait, so this message was not posted.Send the request again in a moment.
internal_errorInternal errorAn unexpected error occurred while handling the request.Retry; if persistent, inspect the daemon logs.
service_unavailableService unavailableThe daemon could not service the request because it was too busy, or a per-client stream concurrency cap was hit.Honor Retry-After and retry.
restriction_unknownLogin restriction unknownThe agent cannot read yet which realms its login may serve (GET /api/v1/agent/hoody/auth/status reports restriction unknown), so it refuses realm-scoped requests until it can. Nothing was read or changed.Retry after the restriction is readable.

POST /api/v1/agent/bots/{realm}/{bot}/{door}

Section titled “POST /api/v1/agent/bots/{realm}/{bot}/{door}”

Posts the last user message to the Bot through the named door. The answer can use JSON in the client’s format or Server-Sent Events. A POST of /mcp is an MCP request. The Authorization and x-api-key headers are ignored: apps may send any value, and access is decided before the request reaches the agent.

NameInTypeRequiredDescription
realmpathstringYesThe realm.
botpathstringYesThe bot.
doorpathstringYesThe door.
NameTypeRequiredDescription
modelstringNoIgnored because the URL names the Bot.
messagesarrayNoThe conversation. Only the last message besides system and developer messages is posted, and it must be a user message. Each item requires role and content.
streambooleanNotrue answers with Server-Sent Events. Default: false.
stream_optionsobjectNoStream options.
stream_options.include_usagebooleanNoSend a usage chunk at the end of the stream.
max_tokensintegerNoOutput budget. It must be a positive integer; 64 or less marks a side request.
max_completion_tokensintegerNoOutput budget. It wins over max_tokens when both are sent.
userstringNoThe end user’s id. It is part of what makes a request the same request sent again.
inputstring | arrayNoThe message as a string, or a list of input items whose last message besides system and developer messages is a user message.
instructionsstringNoCounts as the system prompt.
max_output_tokensintegerNoOutput budget. It must be a positive integer; 64 or less marks a side request.
systemstring | arrayNoThe system prompt, as a string or text blocks.
metadataobjectNoRequest metadata.
metadata.user_idstringNoThe end user’s id. It is part of what makes a request the same request sent again.
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief/v1/chat/completions" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: req-2026-10-08-002" \
--data '{"messages":[{"role":"user","content":"What is the status of the release?"}]}'

200

Media type: application/json, text/event-stream

{
"id": "chatcmpl-bot-0199c3a2",
"object": "chat.completion",
"created": 1762533000,
"model": "bot:global/chief",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "I'll start by checking the current state of the release pipeline."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 42,
"completion_tokens": 18,
"total_tokens": 60
}
}

The response can be application/json, containing a chat completion, Responses response, Anthropic message or MCP reply, or text/event-stream. Chat and model errors use the client format’s own error body (OpenAI, or Anthropic for /v1/messages and for a model request carrying anthropic-version).

400

Media type: application/json

{
"code": "bad_request",
"message": "invalid request"
}

403

Media type: application/json

{
"code": "forbidden",
"message": "Hoody Kit programs are reached through their URLs only"
}

404

Media type: application/json

{
"code": "not_found",
"message": "resource not found"
}

409

Media type: application/json

{
"code": "realm_blocked",
"message": "realm is blocked"
}

413

Media type: application/json

{
"code": "payload_too_large",
"message": "request body exceeds the configured size limit"
}

422

Media type: application/json

{
"code": "idempotency_key_reused",
"message": "this Idempotency-Key was used for a different message"
}

429

Media type: application/json

{
"code": "rate_limited",
"message": "request rate limit exceeded"
}

500

Media type: application/json

{
"code": "internal_error",
"message": "internal server error"
}

502

Media type: application/json

{
"error": {
"message": "the Bot's model cannot limit the length of this request's answer, so it was not sent",
"type": "api_error",
"param": null,
"code": "upstream_error"
}
}

503

Media type: application/json

{
"code": "service_unavailable",
"message": "service unavailable"
}
Error CodeTitleDescriptionResolution
bad_requestBad requestThe request was malformed or carried invalid parameters.Correct the request body or query parameters.
realm_scope_unsupportedRealm scope unsupportedA per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm.Omit the header, or name the realm the agent is pinned to.
invalid_realmInvalid realm selectorThe realm selector is malformed (not ""/"global"/a 24-hex id).Pass a valid realm selector.
forbiddenForbidden (Source IP Guard)Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.Call the agent through its URL, for example with hoody agent ….
not_foundNot foundThe requested resource does not exist.Verify the path and identifier.
realm_blockedRealm blockedThe requested realm is blocked or corrupt; the request fails closed before dispatch.Select a valid, reachable realm.
bot_owned_elsewhereBot served by another agentAnother agent process on this machine serves the Bot (details.reason held), or its owner lock cannot be taken on this filesystem (details.reason lock_unavailable). Nothing of the Bot was read or changed. The answer carries Retry-After: 5. details.owner names the serving process (pid, started_at) when known, else null.Retry after Retry-After seconds, or reach the Bot through the agent that serves it. The Bot list includes such a Bot as a row with owned_elsewhere: true.
payload_too_largePayload too largeThe request body exceeds the configured size limit (default 8 MiB). Reduce the request body.Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.
idempotency_key_reusedIdempotency key reusedThe Idempotency-Key already accepted a different message for this Bot.Use a fresh Idempotency-Key for a different message, or resend the identical message to get its answer.
rate_limitedToo many requestsThe per-client request rate limit was exceeded; the gateway throttled the request before dispatch.Honor the Retry-After header and retry; reduce the request rate.
idempotency_keys_exhaustedToo many remembered keysThe Bot already remembers 4096 Idempotency-Key values, each while its message is queued and for at least 24 hours after the message was accepted. Nothing was queued.Send the message later, when older keys have expired, or send it without an Idempotency-Key.
bot_busyBot busyThe Bot was answering other requests for the whole wait, so this message was not posted.Send the request again in a moment.
internal_errorInternal errorAn unexpected error occurred while handling the request.Retry; if persistent, inspect the daemon logs.
upstream_errorSide request cannot be cappedThe request is a side request, such as a title, summary, follow-up suggestions, tags or autocompletion, and the Bot’s model cannot limit the length of its answer. The request was not sent to the model, so nothing was spent. With stream true, this is still an ordinary error response, never an event stream.Turn the app’s side tasks off for this Bot, or give the Bot a model that takes an output limit.
service_unavailableService unavailableThe daemon could not service the request because it was too busy, or a per-client stream concurrency cap was hit.Honor Retry-After and retry.
restriction_unknownLogin restriction unknownThe agent cannot read yet which realms its login may serve (GET /api/v1/agent/hoody/auth/status reports restriction unknown), so it refuses realm-scoped requests until it can. Nothing was read or changed.Retry after the restriction is readable.

The MCP server is stateless and has no session to end, so a DELETE of /mcp or the base URL answers 405 (Allow: POST). A DELETE of any other door is 404. The 200 response is documented for completeness but is not actually returned in practice.

NameInTypeRequiredDescription
realmpathstringYesThe realm.
botpathstringYesThe bot.
Terminal window
curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief" \
-H "Authorization: Bearer <token>"

200

Media type: application/json

Not actually returned. The MCP server is stateless: DELETE of /mcp or the base URL answers 405 (Allow: POST), and DELETE of any other door is 404.

400

Media type: application/json

{
"code": "bad_request",
"message": "invalid request"
}

403

Media type: application/json

{
"code": "forbidden",
"message": "Hoody Kit programs are reached through their URLs only"
}

404

Media type: application/json

{
"code": "not_found",
"message": "resource not found"
}

405

Media type: application/json

{
"code": "method_not_allowed",
"message": "this MCP server sends no stream and keeps no session: POST each request"
}

409

Media type: application/json

{
"code": "realm_blocked",
"message": "realm is blocked"
}

429

Media type: application/json

{
"code": "rate_limited",
"message": "request rate limit exceeded"
}

500

Media type: application/json

{
"code": "internal_error",
"message": "internal server error"
}

503

Media type: application/json

{
"code": "service_unavailable",
"message": "service unavailable"
}
Error CodeTitleDescriptionResolution
bad_requestBad requestThe request was malformed or carried invalid parameters.Correct the request body or query parameters.
realm_scope_unsupportedRealm scope unsupportedA per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm.Omit the header, or name the realm the agent is pinned to.
invalid_realmInvalid realm selectorThe realm selector is malformed (not ""/"global"/a 24-hex id).Pass a valid realm selector.
forbiddenForbidden (Source IP Guard)Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.Call the agent through its URL, for example with hoody agent ….
not_foundNot foundThe requested resource does not exist.Verify the path and identifier.
method_not_allowedMethod not allowedThe MCP server keeps no session and no ongoing Bot-update stream; use …/events for live updates; a standalone GET event stream gets 405. The answer carries Allow: POST.POST each MCP request.
realm_blockedRealm blockedThe requested realm is blocked or corrupt; the request fails closed before dispatch.Select a valid, reachable realm.
bot_owned_elsewhereBot served by another agentAnother agent process on this machine serves the Bot (details.reason held), or its owner lock cannot be taken on this filesystem (details.reason lock_unavailable). Nothing of the Bot was read or changed. The answer carries Retry-After: 5. details.owner names the serving process (pid, started_at) when known, else null.Retry after Retry-After seconds, or reach the Bot through the agent that serves it. The Bot list includes such a Bot as a row with owned_elsewhere: true.
rate_limitedToo many requestsThe per-client request rate limit was exceeded; the gateway throttled the request before dispatch.Honor the Retry-After header and retry; reduce the request rate.
internal_errorInternal errorAn unexpected error occurred while handling the request.Retry; if persistent, inspect the daemon logs.
service_unavailableService unavailableThe daemon could not service the request because it was too busy, or a per-client stream concurrency cap was hit.Honor Retry-After and retry.
restriction_unknownLogin restriction unknownThe agent cannot read yet which realms its login may serve (GET /api/v1/agent/hoody/auth/status reports restriction unknown), so it refuses realm-scoped requests until it can. Nothing was read or changed.Retry after the restriction is readable.

DELETE /api/v1/agent/bots/{realm}/{bot}/{door}

Section titled “DELETE /api/v1/agent/bots/{realm}/{bot}/{door}”

The MCP server is stateless and has no session to end, so a DELETE of /mcp or the base URL answers 405 (Allow: POST). A DELETE of any other door is 404. The 200 response is documented for completeness but is not actually returned in practice.

NameInTypeRequiredDescription
realmpathstringYesThe realm.
botpathstringYesThe bot.
doorpathstringYesThe door.
Terminal window
curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief/mcp" \
-H "Authorization: Bearer <token>"

200

Media type: application/json

Not actually returned. The MCP server is stateless: DELETE of /mcp or the base URL answers 405 (Allow: POST), and DELETE of any other door is 404.

400

Media type: application/json

{
"code": "bad_request",
"message": "invalid request"
}

403

Media type: application/json

{
"code": "forbidden",
"message": "Hoody Kit programs are reached through their URLs only"
}

404

Media type: application/json

{
"code": "not_found",
"message": "resource not found"
}

405

Media type: application/json

{
"code": "method_not_allowed",
"message": "this MCP server sends no stream and keeps no session: POST each request"
}

409

Media type: application/json

{
"code": "realm_blocked",
"message": "realm is blocked"
}

429

Media type: application/json

{
"code": "rate_limited",
"message": "request rate limit exceeded"
}

500

Media type: application/json

{
"code": "internal_error",
"message": "internal server error"
}

503

Media type: application/json

{
"code": "service_unavailable",
"message": "service unavailable"
}
Error CodeTitleDescriptionResolution
bad_requestBad requestThe request was malformed or carried invalid parameters.Correct the request body or query parameters.
realm_scope_unsupportedRealm scope unsupportedA per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm.Omit the header, or name the realm the agent is pinned to.
invalid_realmInvalid realm selectorThe realm selector is malformed (not ""/"global"/a 24-hex id).Pass a valid realm selector.
forbiddenForbidden (Source IP Guard)Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.Call the agent through its URL, for example with hoody agent ….
not_foundNot foundThe requested resource does not exist.Verify the path and identifier.
method_not_allowedMethod not allowedThe MCP server keeps no session and no ongoing Bot-update stream; use …/events for live updates; a standalone GET event stream gets 405. The answer carries Allow: POST.POST each MCP request.
realm_blockedRealm blockedThe requested realm is blocked or corrupt; the request fails closed before dispatch.Select a valid, reachable realm.
bot_owned_elsewhereBot served by another agentAnother agent process on this machine serves the Bot (details.reason held), or its owner lock cannot be taken on this filesystem (details.reason lock_unavailable). Nothing of the Bot was read or changed. The answer carries Retry-After: 5. details.owner names the serving process (pid, started_at) when known, else null.Retry after Retry-After seconds, or reach the Bot through the agent that serves it. The Bot list includes such a Bot as a row with owned_elsewhere: true.
rate_limitedToo many requestsThe per-client request rate limit was exceeded; the gateway throttled the request before dispatch.Honor the Retry-After header and retry; reduce the request rate.
internal_errorInternal errorAn unexpected error occurred while handling the request.Retry; if persistent, inspect the daemon logs.
service_unavailableService unavailableThe daemon could not service the request because it was too busy, or a per-client stream concurrency cap was hit.Honor Retry-After and retry.
restriction_unknownLogin restriction unknownThe agent cannot read yet which realms its login may serve (GET /api/v1/agent/hoody/auth/status reports restriction unknown), so it refuses realm-scoped requests until it can. Nothing was read or changed.Retry after the restriction is readable.

The compat paths under /api/v1/agent/compat/anthropic/v1/... reach the same Bots as the Bot URL. Each Bot is a model whose id is its address, bot:<realm>/<id> (for example bot:global/chief); a bare Bot id names a Bot of the realm X-Hoody-Realm names, else of the agent’s current realm. The Authorization and x-api-key headers are ignored: apps may send any value, and access is decided before the request reaches the agent. Errors use this format’s own error body, not the agent’s. The path is read forgivingly: repeated slashes, a trailing slash, a missing or doubled /v1, and a whole …/chat/completions or …/messages URL pasted as the base all reach the same route.

GET /api/v1/agent/compat/anthropic/v1/models

Section titled “GET /api/v1/agent/compat/anthropic/v1/models”

Lists every Bot of every realm this login serves (an agent pinned to one realm: that realm’s Bots), in the Anthropic-compatible model list shape.

NameInTypeRequiredDescription
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header, read when the header is absent or empty: global (not tied to a realm) or a 24-hex realm id. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/compat/anthropic/v1/models" \
-H "x-api-key: <token>"

200

Media type: application/json

{
"data": [
{
"type": "model",
"id": "bot:global/chief",
"display_name": "Chief",
"created_at": "2026-10-08T10:30:00Z"
}
],
"has_more": false,
"first_id": "bot:global/chief",
"last_id": "bot:global/chief"
}

400

Media type: application/json

{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "invalid request",
"code": "bad_request"
}
}

403

Media type: application/json

{
"type": "error",
"error": {
"type": "api_error",
"message": "Hoody Kit programs are reached through their URLs only",
"code": "forbidden"
}
}

404

Media type: application/json

{
"type": "error",
"error": {
"type": "not_found_error",
"message": "resource not found",
"code": "not_found"
}
}

409

Media type: application/json

{
"type": "error",
"error": {
"type": "api_error",
"message": "realm is blocked",
"code": "realm_blocked"
}
}

429

Media type: application/json

{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "request rate limit exceeded",
"code": "rate_limited"
}
}

500

Media type: application/json

{
"type": "error",
"error": {
"type": "api_error",
"message": "internal server error",
"code": "internal_error"
}
}

503

Media type: application/json

{
"type": "error",
"error": {
"type": "overloaded_error",
"message": "service unavailable",
"code": "service_unavailable"
}
}
Error CodeTitleDescriptionResolution
bad_requestBad requestThe request was malformed or carried invalid parameters.Correct the request body or query parameters.
realm_scope_unsupportedRealm scope unsupportedA per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm.Omit the header, or name the realm the agent is pinned to.
invalid_realmInvalid realm selectorThe realm selector is malformed (not ""/"global"/a 24-hex id).Pass a valid realm selector.
forbiddenForbidden (Source IP Guard)Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.Call the agent through its URL, for example with hoody agent ….
not_foundNot foundThe requested resource does not exist.Verify the path and identifier.
realm_blockedRealm blockedThe requested realm is blocked or corrupt; the request fails closed before dispatch.Select a valid, reachable realm.
rate_limitedToo many requestsThe per-client request rate limit was exceeded; the gateway throttled the request before dispatch.Honor the Retry-After header and retry; reduce the request rate.
internal_errorInternal errorAn unexpected error occurred while handling the request.Retry; if persistent, inspect the daemon logs.
service_unavailableService unavailableThe daemon could not service the request because it was too busy, or a per-client stream concurrency cap was hit.Honor Retry-After and retry.
restriction_unknownLogin restriction unknownThe agent cannot read yet which realms its login may serve (GET /api/v1/agent/hoody/auth/status reports restriction unknown), so it refuses realm-scoped requests until it can. Nothing was read or changed.Retry after the restriction is readable.

GET /api/v1/agent/compat/anthropic/v1/models/{model}

Section titled “GET /api/v1/agent/compat/anthropic/v1/models/{model}”

Reads the Bot named model in the Anthropic-compatible model shape. An unknown Bot, or a realm this login does not serve, answers 404.

NameInTypeRequiredDescription
modelpathstringYesThe model.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header, read when the header is absent or empty: global (not tied to a realm) or a 24-hex realm id. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/compat/anthropic/v1/models/bot:global/chief" \
-H "x-api-key: <token>"

200

Media type: application/json

{
"type": "model",
"id": "bot:global/chief",
"display_name": "Chief",
"created_at": "2026-10-08T10:30:00Z"
}

400

Media type: application/json

{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "invalid request",
"code": "bad_request"
}
}

403

Media type: application/json

{
"type": "error",
"error": {
"type": "api_error",
"message": "Hoody Kit programs are reached through their URLs only",
"code": "forbidden"
}
}

404

Media type: application/json

{
"type": "error",
"error": {
"type": "not_found_error",
"message": "no such model: no Bot with this id in a realm this login serves",
"code": "model_not_found"
}
}

409

Media type: application/json

{
"type": "error",
"error": {
"type": "api_error",
"message": "realm is blocked",
"code": "realm_blocked"
}
}

429

Media type: application/json

{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "request rate limit exceeded",
"code": "rate_limited"
}
}

500

Media type: application/json

{
"type": "error",
"error": {
"type": "api_error",
"message": "internal server error",
"code": "internal_error"
}
}

503

Media type: application/json

{
"type": "error",
"error": {
"type": "overloaded_error",
"message": "service unavailable",
"code": "service_unavailable"
}
}
Error CodeTitleDescriptionResolution
bad_requestBad requestThe request was malformed or carried invalid parameters.Correct the request body or query parameters.
realm_scope_unsupportedRealm scope unsupportedA per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm.Omit the header, or name the realm the agent is pinned to.
invalid_realmInvalid realm selectorThe realm selector is malformed (not ""/"global"/a 24-hex id).Pass a valid realm selector.
forbiddenForbidden (Source IP Guard)Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.Call the agent through its URL, for example with hoody agent ….
not_foundNot foundThe requested resource does not exist.Verify the path and identifier.
model_not_foundNo such modelNo Bot has this id in a realm this login serves.List the models and use one of their ids.
realm_blockedRealm blockedThe requested realm is blocked or corrupt; the request fails closed before dispatch.Select a valid, reachable realm.
bot_owned_elsewhereBot served by another agentAnother agent process on this machine serves the Bot (details.reason held), or its owner lock cannot be taken on this filesystem (details.reason lock_unavailable). Nothing of the Bot was read or changed. The answer carries Retry-After: 5. details.owner names the serving process (pid, started_at) when known, else null.Retry after Retry-After seconds, or reach the Bot through the agent that serves it. The Bot list includes such a Bot as a row with owned_elsewhere: true.
rate_limitedToo many requestsThe per-client request rate limit was exceeded; the gateway throttled the request before dispatch.Honor the Retry-After header and retry; reduce the request rate.
internal_errorInternal errorAn unexpected error occurred while handling the request.Retry; if persistent, inspect the daemon logs.
service_unavailableService unavailableThe daemon could not service the request because it was too busy, or a per-client stream concurrency cap was hit.Honor Retry-After and retry.
restriction_unknownLogin restriction unknownThe agent cannot read yet which realms its login may serve (GET /api/v1/agent/hoody/auth/status reports restriction unknown), so it refuses realm-scoped requests until it can. Nothing was read or changed.Retry after the restriction is readable.

POST /api/v1/agent/compat/anthropic/v1/messages

Section titled “POST /api/v1/agent/compat/anthropic/v1/messages”

Posts the last user message to the selected Bot and answers with the Bot’s reply in the Anthropic Messages shape. The response can be JSON or Server-Sent Events. With a streamed response, the body carries the message_start through message_stop events instead of a JSON message. Which message is read, side requests, how the answer waits for delegates, and Idempotency-Key work as on a Bot URL (see Open a Bot URL above).

NameInTypeRequiredDescription
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header, read when the header is absent or empty: global (not tied to a realm) or a 24-hex realm id. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
NameTypeRequiredDescription
modelstringYesThe Bot to talk to, as …/models lists it: bot:<realm>/<id>.
messagesarrayYesThe conversation. Only the last message is posted, and it must be a user message. Each item requires role and content.
messages[].rolestringYesuser, assistant, or an instruction role such as system.
messages[].contentstring | arrayYesThe text, or a list of content parts. The last message takes text parts only.
systemstring | arrayNoThe system prompt, as a string or text blocks.
max_tokensintegerNoOutput budget. It must be a positive integer; 64 or less marks a side request.
streambooleanNotrue answers with Server-Sent Events. Default: false.
metadataobjectNoRequest metadata.
metadata.user_idstringNoThe end user’s id. It is part of what makes a request the same request sent again.
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/compat/anthropic/v1/messages" \
-H "anthropic-version: 2023-06-01" \
-H "x-api-key: <token>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: req-2026-10-08-003" \
--data '{"model":"bot:global/chief","messages":[{"role":"user","content":"What is the status of the release?"}],"max_tokens":1024}'

200

Media type: application/json

{
"id": "msg_bot_0199c3a2",
"type": "message",
"role": "assistant",
"model": "bot:global/chief",
"content": [
{
"type": "text",
"text": "I'll start by checking the current state of the release pipeline."
}
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 42,
"output_tokens": 18,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0
}
}

400

Media type: application/json

{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "invalid request",
"code": "bad_request"
}
}

403

Media type: application/json

{
"type": "error",
"error": {
"type": "api_error",
"message": "Hoody Kit programs are reached through their URLs only",
"code": "forbidden"
}
}

404

Media type: application/json

{
"type": "error",
"error": {
"type": "not_found_error",
"message": "no such model: no Bot with this id in a realm this login serves",
"code": "model_not_found"
}
}

409

Media type: application/json

{
"type": "error",
"error": {
"type": "api_error",
"message": "realm is blocked",
"code": "realm_blocked"
}
}

413

Media type: application/json

{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "request body exceeds the configured size limit",
"code": "payload_too_large"
}
}

422

Media type: application/json

{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "this Idempotency-Key was used for a different message",
"code": "idempotency_key_reused"
}
}

429

Media type: application/json

{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "request rate limit exceeded",
"code": "rate_limited"
}
}

500

Media type: application/json

{
"type": "error",
"error": {
"type": "api_error",
"message": "internal server error",
"code": "internal_error"
}
}

502

Media type: application/json

{
"type": "error",
"error": {
"type": "api_error",
"message": "the Bot's model cannot limit the length of this request's answer, so it was not sent",
"code": "upstream_error"
}
}

503

Media type: application/json

{
"type": "error",
"error": {
"type": "overloaded_error",
"message": "service unavailable",
"code": "service_unavailable"
}
}
Error CodeTitleDescriptionResolution
bad_requestBad requestThe request was malformed or carried invalid parameters.Correct the request body or query parameters.
realm_scope_unsupportedRealm scope unsupportedA per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm.Omit the header, or name the realm the agent is pinned to.
invalid_realmInvalid realm selectorThe realm selector is malformed (not ""/"global"/a 24-hex id).Pass a valid realm selector.
forbiddenForbidden (Source IP Guard)Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.Call the agent through its URL, for example with hoody agent ….
not_foundNot foundThe requested resource does not exist.Verify the path and identifier.
model_not_foundNo such modelNo Bot has this id in a realm this login serves.List the models and use one of their ids.
realm_blockedRealm blockedThe requested realm is blocked or corrupt; the request fails closed before dispatch.Select a valid, reachable realm.
bot_owned_elsewhereBot served by another agentAnother agent process on this machine serves the Bot (details.reason held), or its owner lock cannot be taken on this filesystem (details.reason lock_unavailable). Nothing of the Bot was read or changed. The answer carries Retry-After: 5. details.owner names the serving process (pid, started_at) when known, else null.Retry after Retry-After seconds, or reach the Bot through the agent that serves it. The Bot list includes such a Bot as a row with owned_elsewhere: true.
payload_too_largePayload too largeThe request body exceeds the configured size limit (default 8 MiB). Reduce the request body.Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.
idempotency_key_reusedIdempotency key reusedThe Idempotency-Key already accepted a different message for this Bot.Use a fresh Idempotency-Key for a different message, or resend the identical message to get its answer.
rate_limitedToo many requestsThe per-client request rate limit was exceeded; the gateway throttled the request before dispatch.Honor the Retry-After header and retry; reduce the request rate.
idempotency_keys_exhaustedToo many remembered keysThe Bot already remembers 4096 Idempotency-Key values, each while its message is queued and for at least 24 hours after the message was accepted. Nothing was queued.Send the message later, when older keys have expired, or send it without an Idempotency-Key.
bot_busyBot busyThe Bot was answering other requests for the whole wait, so this message was not posted.Send the request again in a moment.
internal_errorInternal errorAn unexpected error occurred while handling the request.Retry; if persistent, inspect the daemon logs.
upstream_errorSide request cannot be cappedThe request is a side request, such as a title, summary, follow-up suggestions, tags or autocompletion, and the Bot’s model cannot limit the length of its answer. The request was not sent to the model, so nothing was spent. With stream true, this is still an ordinary error response, never an event stream.Turn the app’s side tasks off for this Bot, or give the Bot a model that takes an output limit.
service_unavailableService unavailableThe daemon could not service the request because it was too busy, or a per-client stream concurrency cap was hit.Honor Retry-After and retry.
restriction_unknownLogin restriction unknownThe agent cannot read yet which realms its login may serve (GET /api/v1/agent/hoody/auth/status reports restriction unknown), so it refuses realm-scoped requests until it can. Nothing was read or changed.Retry after the restriction is readable.

The compat paths under /api/v1/agent/compat/openai/v1/... reach the same Bots as the Bot URL. Each Bot is a model whose id is its address, bot:<realm>/<id> (for example bot:global/chief); a bare Bot id names a Bot of the realm X-Hoody-Realm names, else of the agent’s current realm. The Authorization and x-api-key headers are ignored: apps may send any value, and access is decided before the request reaches the agent. Errors use this format’s own error body, not the agent’s. The path is read forgivingly: repeated slashes, a trailing slash, a missing or doubled /v1, and a whole …/chat/completions or …/messages URL pasted as the base all reach the same route.

Lists every Bot of every realm this login serves (an agent pinned to one realm: that realm’s Bots), in the OpenAI-compatible model list shape.

NameInTypeRequiredDescription
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header, read when the header is absent or empty: global (not tied to a realm) or a 24-hex realm id. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/compat/openai/v1/models" \
-H "Authorization: Bearer <token>"

200

Media type: application/json

{
"object": "list",
"data": [
{
"id": "bot:global/chief",
"object": "model",
"created": 1762533000,
"owned_by": "hoody"
}
]
}

400

Media type: application/json

{
"error": {
"message": "invalid request",
"type": "invalid_request_error",
"param": null,
"code": "bad_request"
}
}

403

Media type: application/json

{
"error": {
"message": "Hoody Kit programs are reached through their URLs only",
"type": "api_error",
"param": null,
"code": "forbidden"
}
}

404

Media type: application/json

{
"error": {
"message": "resource not found",
"type": "not_found_error",
"param": null,
"code": "not_found"
}
}

409

Media type: application/json

{
"error": {
"message": "realm is blocked",
"type": "api_error",
"param": null,
"code": "realm_blocked"
}
}

429

Media type: application/json

{
"error": {
"message": "request rate limit exceeded",
"type": "rate_limit_error",
"param": null,
"code": "rate_limited"
}
}

500

Media type: application/json

{
"error": {
"message": "internal server error",
"type": "api_error",
"param": null,
"code": "internal_error"
}
}

503

Media type: application/json

{
"error": {
"message": "service unavailable",
"type": "api_error",
"param": null,
"code": "service_unavailable"
}
}
Error CodeTitleDescriptionResolution
bad_requestBad requestThe request was malformed or carried invalid parameters.Correct the request body or query parameters.
realm_scope_unsupportedRealm scope unsupportedA per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm.Omit the header, or name the realm the agent is pinned to.
invalid_realmInvalid realm selectorThe realm selector is malformed (not ""/"global"/a 24-hex id).Pass a valid realm selector.
forbiddenForbidden (Source IP Guard)Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.Call the agent through its URL, for example with hoody agent ….
not_foundNot foundThe requested resource does not exist.Verify the path and identifier.
realm_blockedRealm blockedThe requested realm is blocked or corrupt; the request fails closed before dispatch.Select a valid, reachable realm.
rate_limitedToo many requestsThe per-client request rate limit was exceeded; the gateway throttled the request before dispatch.Honor the Retry-After header and retry; reduce the request rate.
internal_errorInternal errorAn unexpected error occurred while handling the request.Retry; if persistent, inspect the daemon logs.
service_unavailableService unavailableThe daemon could not service the request because it was too busy, or a per-client stream concurrency cap was hit.Honor Retry-After and retry.
restriction_unknownLogin restriction unknownThe agent cannot read yet which realms its login may serve (GET /api/v1/agent/hoody/auth/status reports restriction unknown), so it refuses realm-scoped requests until it can. Nothing was read or changed.Retry after the restriction is readable.

GET /api/v1/agent/compat/openai/v1/models/{model}

Section titled “GET /api/v1/agent/compat/openai/v1/models/{model}”

Reads the Bot named model in the OpenAI-compatible model shape. An unknown Bot, or a realm this login does not serve, answers 404.

NameInTypeRequiredDescription
modelpathstringYesThe model.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header, read when the header is absent or empty: global (not tied to a realm) or a 24-hex realm id. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/compat/openai/v1/models/bot:global/chief" \
-H "Authorization: Bearer <token>"

200

Media type: application/json

{
"id": "bot:global/chief",
"object": "model",
"created": 1762533000,
"owned_by": "hoody"
}

400

Media type: application/json

{
"error": {
"message": "invalid request",
"type": "invalid_request_error",
"param": null,
"code": "bad_request"
}
}

403

Media type: application/json

{
"error": {
"message": "Hoody Kit programs are reached through their URLs only",
"type": "api_error",
"param": null,
"code": "forbidden"
}
}

404

Media type: application/json

{
"error": {
"message": "no such model: no Bot with this id in a realm this login serves",
"type": "not_found_error",
"param": null,
"code": "model_not_found"
}
}

409

Media type: application/json

{
"error": {
"message": "realm is blocked",
"type": "api_error",
"param": null,
"code": "realm_blocked"
}
}

429

Media type: application/json

{
"error": {
"message": "request rate limit exceeded",
"type": "rate_limit_error",
"param": null,
"code": "rate_limited"
}
}

500

Media type: application/json

{
"error": {
"message": "internal server error",
"type": "api_error",
"param": null,
"code": "internal_error"
}
}

503

Media type: application/json

{
"error": {
"message": "service unavailable",
"type": "api_error",
"param": null,
"code": "service_unavailable"
}
}
Error CodeTitleDescriptionResolution
bad_requestBad requestThe request was malformed or carried invalid parameters.Correct the request body or query parameters.
realm_scope_unsupportedRealm scope unsupportedA per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm.Omit the header, or name the realm the agent is pinned to.
invalid_realmInvalid realm selectorThe realm selector is malformed (not ""/"global"/a 24-hex id).Pass a valid realm selector.
forbiddenForbidden (Source IP Guard)Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.Call the agent through its URL, for example with hoody agent ….
not_foundNot foundThe requested resource does not exist.Verify the path and identifier.
model_not_foundNo such modelNo Bot has this id in a realm this login serves.List the models and use one of their ids.
realm_blockedRealm blockedThe requested realm is blocked or corrupt; the request fails closed before dispatch.Select a valid, reachable realm.
bot_owned_elsewhereBot served by another agentAnother agent process on this machine serves the Bot (details.reason held), or its owner lock cannot be taken on this filesystem (details.reason lock_unavailable). Nothing of the Bot was read or changed. The answer carries Retry-After: 5. details.owner names the serving process (pid, started_at) when known, else null.Retry after Retry-After seconds, or reach the Bot through the agent that serves it. The Bot list includes such a Bot as a row with owned_elsewhere: true.
rate_limitedToo many requestsThe per-client request rate limit was exceeded; the gateway throttled the request before dispatch.Honor the Retry-After header and retry; reduce the request rate.
internal_errorInternal errorAn unexpected error occurred while handling the request.Retry; if persistent, inspect the daemon logs.
service_unavailableService unavailableThe daemon could not service the request because it was too busy, or a per-client stream concurrency cap was hit.Honor Retry-After and retry.
restriction_unknownLogin restriction unknownThe agent cannot read yet which realms its login may serve (GET /api/v1/agent/hoody/auth/status reports restriction unknown), so it refuses realm-scoped requests until it can. Nothing was read or changed.Retry after the restriction is readable.

GET /api/v1/agent/compat/openai/v1/realtime

Section titled “GET /api/v1/agent/compat/openai/v1/realtime”

Opens a voice conversation with the Bot. ?model= names the Bot: bot:<realm>/<id>, or a bare Bot id of the realm X-Hoody-Realm names (else the request’s realm). The same conversation as the per-realm Bot URL …/bots/<realm>/<bot>/v1/realtime. One connection controls a Bot’s voice at a time: another is refused 409 voice_busy unless it asks takeover=true. Errors before the upgrade use OpenAI’s error body; an agent with no voice built in answers 404.

NameInTypeRequiredDescription
modelquerystringNoThe Bot: bot:<realm>/<id>, or a Bot id of the request’s realm.
takeoverquerybooleanNotrue takes over from the connection that controls the Bot’s voice now.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header, read when the header is absent or empty: global (not tied to a realm) or a 24-hex realm id. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
Terminal window
curl -i -N \
-H "Connection: Upgrade" \
-H "Upgrade: websocket" \
-H "Sec-WebSocket-Version: 13" \
-H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
"https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/compat/openai/v1/realtime?model=bot:global/chief&takeover=true"

101

Media type: none

The WebSocket upgrade is accepted, and the connection speaks the OpenAI Realtime protocol. The response has no body.

400

Media type: application/json

{
"error": {
"message": "invalid request",
"type": "invalid_request_error",
"param": null,
"code": "bad_request"
}
}

403

Media type: application/json

{
"error": {
"message": "Hoody Kit programs are reached through their URLs only",
"type": "api_error",
"param": null,
"code": "forbidden"
}
}

404

Media type: application/json

{
"error": {
"message": "no such model: no Bot with this id in a realm this login serves",
"type": "not_found_error",
"param": null,
"code": "model_not_found"
}
}

409

Media type: application/json

{
"error": {
"message": "another voice connection controls this Bot",
"type": "api_error",
"param": null,
"code": "voice_busy"
}
}

429

Media type: application/json

{
"error": {
"message": "request rate limit exceeded",
"type": "rate_limit_error",
"param": null,
"code": "rate_limited"
}
}

500

Media type: application/json

{
"error": {
"message": "internal server error",
"type": "api_error",
"param": null,
"code": "internal_error"
}
}

503

Media type: application/json

{
"error": {
"message": "service unavailable",
"type": "api_error",
"param": null,
"code": "service_unavailable"
}
}
Error CodeTitleDescriptionResolution
bad_requestBad requestThe request was malformed or carried invalid parameters.Correct the request body or query parameters.
realm_scope_unsupportedRealm scope unsupportedA per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm.Omit the header, or name the realm the agent is pinned to.
invalid_realmInvalid realm selectorThe realm selector is malformed (not ""/"global"/a 24-hex id).Pass a valid realm selector.
forbiddenForbidden (Source IP Guard)Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.Call the agent through its URL, for example with hoody agent ….
not_foundNot foundThe requested resource does not exist.Verify the path and identifier.
model_not_foundNo such modelNo Bot has this id in a realm this login serves.List the models and use one of their ids.
realm_blockedRealm blockedThe requested realm is blocked or corrupt; the request fails closed before dispatch.Select a valid, reachable realm.
voice_busyVoice busyAnother connection controls this Bot’s voice.Close the other connection, or connect with takeover=true to take over from it.
bot_owned_elsewhereBot served by another agentAnother agent process on this machine serves the Bot (details.reason held), or its owner lock cannot be taken on this filesystem (details.reason lock_unavailable). Nothing of the Bot was read or changed. The answer carries Retry-After: 5. details.owner names the serving process (pid, started_at) when known, else null.Retry after Retry-After seconds, or reach the Bot through the agent that serves it. The Bot list includes such a Bot as a row with owned_elsewhere: true.
rate_limitedToo many requestsThe per-client request rate limit was exceeded; the gateway throttled the request before dispatch.Honor the Retry-After header and retry; reduce the request rate.
internal_errorInternal errorAn unexpected error occurred while handling the request.Retry; if persistent, inspect the daemon logs.
service_unavailableService unavailableThe daemon could not service the request because it was too busy, or a per-client stream concurrency cap was hit.Honor Retry-After and retry.
restriction_unknownLogin restriction unknownThe agent cannot read yet which realms its login may serve (GET /api/v1/agent/hoody/auth/status reports restriction unknown), so it refuses realm-scoped requests until it can. Nothing was read or changed.Retry after the restriction is readable.

POST /api/v1/agent/compat/openai/v1/chat/completions

Section titled “POST /api/v1/agent/compat/openai/v1/chat/completions”

Posts the last user message to the selected Bot and answers with the Bot’s reply in the OpenAI chat completions shape. The response can be JSON or Server-Sent Events. With a streamed response, the body carries the chat.completion.chunk events ending in [DONE] instead of a JSON completion. Which message is read, side requests, how the answer waits for delegates, and Idempotency-Key work as on a Bot URL (see Open a Bot URL above).

NameInTypeRequiredDescription
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header, read when the header is absent or empty: global (not tied to a realm) or a 24-hex realm id. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
NameTypeRequiredDescription
modelstringYesThe Bot to talk to, as …/models lists it: bot:<realm>/<id>.
messagesarrayYesThe conversation. Only the last message besides system and developer messages is posted, and it must be a user message. Each item requires role and content.
messages[].rolestringYesuser, assistant, or an instruction role such as system or developer.
messages[].contentstring | arrayYesThe text, or a list of content parts. The last message takes text parts only.
streambooleanNotrue answers with Server-Sent Events. Default: false.
stream_optionsobjectNoStream options.
stream_options.include_usagebooleanNoSend a usage chunk at the end of the stream.
max_tokensintegerNoOutput budget. It must be a positive integer; 64 or less marks a side request.
max_completion_tokensintegerNoOutput budget. It wins over max_tokens when both are sent.
userstringNoThe end user’s id. It is part of what makes a request the same request sent again.
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/compat/openai/v1/chat/completions" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: req-2026-10-08-004" \
--data '{"model":"bot:global/chief","messages":[{"role":"user","content":"What is the status of the release?"}]}'

200

Media type: application/json

{
"id": "chatcmpl-bot-0199c3a2",
"object": "chat.completion",
"created": 1762533000,
"model": "bot:global/chief",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "I'll start by checking the current state of the release pipeline."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 42,
"completion_tokens": 18,
"total_tokens": 60
}
}

400

Media type: application/json

{
"error": {
"message": "invalid request",
"type": "invalid_request_error",
"param": null,
"code": "bad_request"
}
}

403

Media type: application/json

{
"error": {
"message": "Hoody Kit programs are reached through their URLs only",
"type": "api_error",
"param": null,
"code": "forbidden"
}
}

404

Media type: application/json

{
"error": {
"message": "no such model: no Bot with this id in a realm this login serves",
"type": "not_found_error",
"param": null,
"code": "model_not_found"
}
}

409

Media type: application/json

{
"error": {
"message": "realm is blocked",
"type": "api_error",
"param": null,
"code": "realm_blocked"
}
}

413

Media type: application/json

{
"error": {
"message": "request body exceeds the configured size limit",
"type": "invalid_request_error",
"param": null,
"code": "payload_too_large"
}
}

422

Media type: application/json

{
"error": {
"message": "this Idempotency-Key was used for a different message",
"type": "invalid_request_error",
"param": null,
"code": "idempotency_key_reused"
}
}

429

Media type: application/json

{
"error": {
"message": "request rate limit exceeded",
"type": "rate_limit_error",
"param": null,
"code": "rate_limited"
}
}

500

Media type: application/json

{
"error": {
"message": "internal server error",
"type": "api_error",
"param": null,
"code": "internal_error"
}
}

502

Media type: application/json

{
"error": {
"message": "the Bot's model cannot limit the length of this request's answer, so it was not sent",
"type": "api_error",
"param": null,
"code": "upstream_error"
}
}

503

Media type: application/json

{
"error": {
"message": "service unavailable",
"type": "api_error",
"param": null,
"code": "service_unavailable"
}
}
Error CodeTitleDescriptionResolution
bad_requestBad requestThe request was malformed or carried invalid parameters.Correct the request body or query parameters.
realm_scope_unsupportedRealm scope unsupportedA per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm.Omit the header, or name the realm the agent is pinned to.
invalid_realmInvalid realm selectorThe realm selector is malformed (not ""/"global"/a 24-hex id).Pass a valid realm selector.
forbiddenForbidden (Source IP Guard)Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.Call the agent through its URL, for example with hoody agent ….
not_foundNot foundThe requested resource does not exist.Verify the path and identifier.
model_not_foundNo such modelNo Bot has this id in a realm this login serves.List the models and use one of their ids.
realm_blockedRealm blockedThe requested realm is blocked or corrupt; the request fails closed before dispatch.Select a valid, reachable realm.
bot_owned_elsewhereBot served by another agentAnother agent process on this machine serves the Bot (details.reason held), or its owner lock cannot be taken on this filesystem (details.reason lock_unavailable). Nothing of the Bot was read or changed. The answer carries Retry-After: 5. details.owner names the serving process (pid, started_at) when known, else null.Retry after Retry-After seconds, or reach the Bot through the agent that serves it. The Bot list includes such a Bot as a row with owned_elsewhere: true.
payload_too_largePayload too largeThe request body exceeds the configured size limit (default 8 MiB). Reduce the request body.Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.
idempotency_key_reusedIdempotency key reusedThe Idempotency-Key already accepted a different message for this Bot.Use a fresh Idempotency-Key for a different message, or resend the identical message to get its answer.
rate_limitedToo many requestsThe per-client request rate limit was exceeded; the gateway throttled the request before dispatch.Honor the Retry-After header and retry; reduce the request rate.
idempotency_keys_exhaustedToo many remembered keysThe Bot already remembers 4096 Idempotency-Key values, each while its message is queued and for at least 24 hours after the message was accepted. Nothing was queued.Send the message later, when older keys have expired, or send it without an Idempotency-Key.
bot_busyBot busyThe Bot was answering other requests for the whole wait, so this message was not posted.Send the request again in a moment.
internal_errorInternal errorAn unexpected error occurred while handling the request.Retry; if persistent, inspect the daemon logs.
upstream_errorSide request cannot be cappedThe request is a side request, such as a title, summary, follow-up suggestions, tags or autocompletion, and the Bot’s model cannot limit the length of its answer. The request was not sent to the model, so nothing was spent. With stream true, this is still an ordinary error response, never an event stream.Turn the app’s side tasks off for this Bot, or give the Bot a model that takes an output limit.
service_unavailableService unavailableThe daemon could not service the request because it was too busy, or a per-client stream concurrency cap was hit.Honor Retry-After and retry.
restriction_unknownLogin restriction unknownThe agent cannot read yet which realms its login may serve (GET /api/v1/agent/hoody/auth/status reports restriction unknown), so it refuses realm-scoped requests until it can. Nothing was read or changed.Retry after the restriction is readable.

POST /api/v1/agent/compat/openai/v1/responses

Section titled “POST /api/v1/agent/compat/openai/v1/responses”

Posts the last user message to the selected Bot and answers with the Bot’s reply in the OpenAI Responses shape. The response can be JSON or Server-Sent Events. With a streamed response, the body carries the response.created through response.completed events instead of a JSON response. Nothing is stored: previous_response_id and store are ignored. instructions counts as the system prompt. Which message is read, side requests, how the answer waits for delegates, and Idempotency-Key work as on a Bot URL (see Open a Bot URL above).

NameInTypeRequiredDescription
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header, read when the header is absent or empty: global (not tied to a realm) or a 24-hex realm id. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
NameTypeRequiredDescription
modelstringYesThe Bot to talk to, as …/models lists it: bot:<realm>/<id>.
inputstring | arrayYesThe message as a string, or a list of input items whose last message besides system and developer messages is a user message.
instructionsstringNoCounts as the system prompt.
streambooleanNotrue answers with Server-Sent Events. Default: false.
max_output_tokensintegerNoOutput budget. It must be a positive integer; 64 or less marks a side request.
userstringNoThe end user’s id. It is part of what makes a request the same request sent again.
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/compat/openai/v1/responses" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: req-2026-10-08-005" \
--data '{"model":"bot:global/chief","input":"What is the status of the release?"}'

200

Media type: application/json

{
"id": "resp_bot_0199c3a2",
"object": "response",
"created_at": 1762533000,
"status": "completed",
"model": "bot:global/chief",
"output": [
{
"type": "message",
"id": "msg_bot_0199c3a2",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "I'll start by checking the current state of the release pipeline."
}
]
}
],
"output_text": "I'll start by checking the current state of the release pipeline.",
"usage": {
"input_tokens": 42,
"output_tokens": 18,
"total_tokens": 60
}
}

400

Media type: application/json

{
"error": {
"message": "invalid request",
"type": "invalid_request_error",
"param": null,
"code": "bad_request"
}
}

403

Media type: application/json

{
"error": {
"message": "Hoody Kit programs are reached through their URLs only",
"type": "api_error",
"param": null,
"code": "forbidden"
}
}

404

Media type: application/json

{
"error": {
"message": "no such model: no Bot with this id in a realm this login serves",
"type": "not_found_error",
"param": null,
"code": "model_not_found"
}
}

409

Media type: application/json

{
"error": {
"message": "realm is blocked",
"type": "api_error",
"param": null,
"code": "realm_blocked"
}
}

413

Media type: application/json

{
"error": {
"message": "request body exceeds the configured size limit",
"type": "invalid_request_error",
"param": null,
"code": "payload_too_large"
}
}

422

Media type: application/json

{
"error": {
"message": "this Idempotency-Key was used for a different message",
"type": "invalid_request_error",
"param": null,
"code": "idempotency_key_reused"
}
}

429

Media type: application/json

{
"error": {
"message": "request rate limit exceeded",
"type": "rate_limit_error",
"param": null,
"code": "rate_limited"
}
}

500

Media type: application/json

{
"error": {
"message": "internal server error",
"type": "api_error",
"param": null,
"code": "internal_error"
}
}

502

Media type: application/json

{
"error": {
"message": "the Bot's model cannot limit the length of this request's answer, so it was not sent",
"type": "api_error",
"param": null,
"code": "upstream_error"
}
}

503

Media type: application/json

{
"error": {
"message": "service unavailable",
"type": "api_error",
"param": null,
"code": "service_unavailable"
}
}
Error CodeTitleDescriptionResolution
bad_requestBad requestThe request was malformed or carried invalid parameters.Correct the request body or query parameters.
realm_scope_unsupportedRealm scope unsupportedA per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm.Omit the header, or name the realm the agent is pinned to.
invalid_realmInvalid realm selectorThe realm selector is malformed (not ""/"global"/a 24-hex id).Pass a valid realm selector.
forbiddenForbidden (Source IP Guard)Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.Call the agent through its URL, for example with hoody agent ….
not_foundNot foundThe requested resource does not exist.Verify the path and identifier.
model_not_foundNo such modelNo Bot has this id in a realm this login serves.List the models and use one of their ids.
realm_blockedRealm blockedThe requested realm is blocked or corrupt; the request fails closed before dispatch.Select a valid, reachable realm.
bot_owned_elsewhereBot served by another agentAnother agent process on this machine serves the Bot (details.reason held), or its owner lock cannot be taken on this filesystem (details.reason lock_unavailable). Nothing of the Bot was read or changed. The answer carries Retry-After: 5. details.owner names the serving process (pid, started_at) when known, else null.Retry after Retry-After seconds, or reach the Bot through the agent that serves it. The Bot list includes such a Bot as a row with owned_elsewhere: true.
payload_too_largePayload too largeThe request body exceeds the configured size limit (default 8 MiB). Reduce the request body.Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.
idempotency_key_reusedIdempotency key reusedThe Idempotency-Key already accepted a different message for this Bot.Use a fresh Idempotency-Key for a different message, or resend the identical message to get its answer.
rate_limitedToo many requestsThe per-client request rate limit was exceeded; the gateway throttled the request before dispatch.Honor the Retry-After header and retry; reduce the request rate.
idempotency_keys_exhaustedToo many remembered keysThe Bot already remembers 4096 Idempotency-Key values, each while its message is queued and for at least 24 hours after the message was accepted. Nothing was queued.Send the message later, when older keys have expired, or send it without an Idempotency-Key.
bot_busyBot busyThe Bot was answering other requests for the whole wait, so this message was not posted.Send the request again in a moment.
internal_errorInternal errorAn unexpected error occurred while handling the request.Retry; if persistent, inspect the daemon logs.
upstream_errorSide request cannot be cappedThe request is a side request, such as a title, summary, follow-up suggestions, tags or autocompletion, and the Bot’s model cannot limit the length of its answer. The request was not sent to the model, so nothing was spent. With stream true, this is still an ordinary error response, never an event stream.Turn the app’s side tasks off for this Bot, or give the Bot a model that takes an output limit.
service_unavailableService unavailableThe daemon could not service the request because it was too busy, or a per-client stream concurrency cap was hit.Honor Retry-After and retry.
restriction_unknownLogin restriction unknownThe agent cannot read yet which realms its login may serve (GET /api/v1/agent/hoody/auth/status reports restriction unknown), so it refuses realm-scoped requests until it can. Nothing was read or changed.Retry after the restriction is readable.