Agent: Bot URLs and compatible APIs
Section titled “Agent: Bot URLs and compatible APIs”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.
Find addresses in the Hub
Section titled “Find addresses in the Hub”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.
Open a Bot URL (paste into an app)
Section titled “Open a Bot URL (paste into an app)”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.
GET /api/v1/agent/bots/{realm}/{bot}
Section titled “GET /api/v1/agent/bots/{realm}/{bot}”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).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
realm | path | string | Yes | The realm. |
bot | path | string | Yes | The bot. |
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief" \ -H "Authorization: Bearer <token>"Response
Section titled “Response”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.
Error responses
Section titled “Error responses”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 codes
Section titled “Error codes”| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A 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_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
forbidden | Forbidden (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_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
method_not_allowed | Method not allowed | The 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_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another 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_limited | Too many requests | The 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_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
service_unavailable | Service unavailable | The 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_unknown | Login restriction unknown | The 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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
realm | path | string | Yes | The realm. |
bot | path | string | Yes | The bot. |
door | path | string | Yes | The door. |
takeover | query | boolean | No | …/v1/realtime only: true takes over from the connection that controls the Bot’s voice now. |
Last-Event-ID | header | string | No | …/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. |
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief/mcp" \ -H "Authorization: Bearer <token>"Response
Section titled “Response”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.
Error responses
Section titled “Error responses”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 codes
Section titled “Error codes”| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A 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_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
forbidden | Forbidden (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_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
method_not_allowed | Method not allowed | The 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_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
voice_busy | Voice busy | Another connection controls this Bot’s voice. | Close the other connection, or connect with takeover=true to take over from it. |
bot_owned_elsewhere | Bot served by another agent | Another 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_limited | Too many requests | The 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_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
service_unavailable | Service unavailable | The 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_unknown | Login restriction unknown | The 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}
Section titled “POST /api/v1/agent/bots/{realm}/{bot}”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
realm | path | string | Yes | The realm. |
bot | path | string | Yes | The bot. |
Request body
Section titled “Request body”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.
| Name | Type | Required | Description |
|---|---|---|---|
jsonrpc | string | Yes | Always 2.0. |
id | integer | string | No | The request id. It is absent on a notification. |
method | string | Yes | The MCP method, for example initialize, tools/list, tools/call or ping. |
params | object | No | The method’s parameters. |
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":{}}'Response
Section titled “Response”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.
Error responses
Section titled “Error responses”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 codes
Section titled “Error codes”| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A 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_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
forbidden | Forbidden (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_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another 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_large | Payload too large | The 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_reused | Idempotency key reused | The 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_limited | Too many requests | The 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_exhausted | Too many remembered keys | The 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_busy | Bot busy | The Bot was answering other requests for the whole wait, so this message was not posted. | Send the request again in a moment. |
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
service_unavailable | Service unavailable | The 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_unknown | Login restriction unknown | The 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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
realm | path | string | Yes | The realm. |
bot | path | string | Yes | The bot. |
door | path | string | Yes | The door. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
model | string | No | Ignored because the URL names the Bot. |
messages | array | No | The 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. |
stream | boolean | No | true answers with Server-Sent Events. Default: false. |
stream_options | object | No | Stream options. |
stream_options.include_usage | boolean | No | Send a usage chunk at the end of the stream. |
max_tokens | integer | No | Output budget. It must be a positive integer; 64 or less marks a side request. |
max_completion_tokens | integer | No | Output budget. It wins over max_tokens when both are sent. |
user | string | No | The end user’s id. It is part of what makes a request the same request sent again. |
input | string | array | No | The message as a string, or a list of input items whose last message besides system and developer messages is a user message. |
instructions | string | No | Counts as the system prompt. |
max_output_tokens | integer | No | Output budget. It must be a positive integer; 64 or less marks a side request. |
system | string | array | No | The system prompt, as a string or text blocks. |
metadata | object | No | Request metadata. |
metadata.user_id | string | No | The end user’s id. It is part of what makes a request the same request sent again. |
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?"}]}'Response
Section titled “Response”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).
Error responses
Section titled “Error responses”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 codes
Section titled “Error codes”| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A 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_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
forbidden | Forbidden (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_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another 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_large | Payload too large | The 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_reused | Idempotency key reused | The 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_limited | Too many requests | The 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_exhausted | Too many remembered keys | The 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_busy | Bot busy | The Bot was answering other requests for the whole wait, so this message was not posted. | Send the request again in a moment. |
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
upstream_error | Side request cannot be capped | The 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_unavailable | Service unavailable | The 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_unknown | Login restriction unknown | The 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}
Section titled “DELETE /api/v1/agent/bots/{realm}/{bot}”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
realm | path | string | Yes | The realm. |
bot | path | string | Yes | The bot. |
curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief" \ -H "Authorization: Bearer <token>"Response
Section titled “Response”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.
Error responses
Section titled “Error responses”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 codes
Section titled “Error codes”| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A 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_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
forbidden | Forbidden (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_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
method_not_allowed | Method not allowed | The 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_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another 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_limited | Too many requests | The 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_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
service_unavailable | Service unavailable | The 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_unknown | Login restriction unknown | The 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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
realm | path | string | Yes | The realm. |
bot | path | string | Yes | The bot. |
door | path | string | Yes | The door. |
curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief/mcp" \ -H "Authorization: Bearer <token>"Response
Section titled “Response”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.
Error responses
Section titled “Error responses”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 codes
Section titled “Error codes”| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A 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_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
forbidden | Forbidden (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_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
method_not_allowed | Method not allowed | The 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_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another 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_limited | Too many requests | The 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_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
service_unavailable | Service unavailable | The 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_unknown | Login restriction unknown | The 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. |
Anthropic-compatibility API
Section titled “Anthropic-compatibility API”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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. |
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/compat/anthropic/v1/models" \ -H "x-api-key: <token>"Response
Section titled “Response”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"}Error responses
Section titled “Error responses”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 codes
Section titled “Error codes”| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A 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_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
forbidden | Forbidden (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_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
rate_limited | Too many requests | The 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_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
service_unavailable | Service unavailable | The 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_unknown | Login restriction unknown | The 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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
model | path | string | Yes | The model. |
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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. |
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>"Response
Section titled “Response”200
Media type: application/json
{ "type": "model", "id": "bot:global/chief", "display_name": "Chief", "created_at": "2026-10-08T10:30:00Z"}Error responses
Section titled “Error responses”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 codes
Section titled “Error codes”| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A 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_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
forbidden | Forbidden (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_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
model_not_found | No such model | No Bot has this id in a realm this login serves. | List the models and use one of their ids. |
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another 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_limited | Too many requests | The 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_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
service_unavailable | Service unavailable | The 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_unknown | Login restriction unknown | The 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).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
model | string | Yes | The Bot to talk to, as …/models lists it: bot:<realm>/<id>. |
messages | array | Yes | The conversation. Only the last message is posted, and it must be a user message. Each item requires role and content. |
messages[].role | string | Yes | user, assistant, or an instruction role such as system. |
messages[].content | string | array | Yes | The text, or a list of content parts. The last message takes text parts only. |
system | string | array | No | The system prompt, as a string or text blocks. |
max_tokens | integer | No | Output budget. It must be a positive integer; 64 or less marks a side request. |
stream | boolean | No | true answers with Server-Sent Events. Default: false. |
metadata | object | No | Request metadata. |
metadata.user_id | string | No | The end user’s id. It is part of what makes a request the same request sent again. |
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}'Response
Section titled “Response”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 }}Error responses
Section titled “Error responses”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 codes
Section titled “Error codes”| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A 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_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
forbidden | Forbidden (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_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
model_not_found | No such model | No Bot has this id in a realm this login serves. | List the models and use one of their ids. |
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another 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_large | Payload too large | The 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_reused | Idempotency key reused | The 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_limited | Too many requests | The 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_exhausted | Too many remembered keys | The 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_busy | Bot busy | The Bot was answering other requests for the whole wait, so this message was not posted. | Send the request again in a moment. |
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
upstream_error | Side request cannot be capped | The 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_unavailable | Service unavailable | The 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_unknown | Login restriction unknown | The 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. |
OpenAI-compatibility API
Section titled “OpenAI-compatibility API”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.
GET /api/v1/agent/compat/openai/v1/models
Section titled “GET /api/v1/agent/compat/openai/v1/models”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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. |
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/compat/openai/v1/models" \ -H "Authorization: Bearer <token>"Response
Section titled “Response”200
Media type: application/json
{ "object": "list", "data": [ { "id": "bot:global/chief", "object": "model", "created": 1762533000, "owned_by": "hoody" } ]}Error responses
Section titled “Error responses”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 codes
Section titled “Error codes”| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A 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_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
forbidden | Forbidden (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_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
rate_limited | Too many requests | The 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_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
service_unavailable | Service unavailable | The 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_unknown | Login restriction unknown | The 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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
model | path | string | Yes | The model. |
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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. |
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>"Response
Section titled “Response”200
Media type: application/json
{ "id": "bot:global/chief", "object": "model", "created": 1762533000, "owned_by": "hoody"}Error responses
Section titled “Error responses”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 codes
Section titled “Error codes”| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A 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_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
forbidden | Forbidden (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_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
model_not_found | No such model | No Bot has this id in a realm this login serves. | List the models and use one of their ids. |
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another 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_limited | Too many requests | The 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_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
service_unavailable | Service unavailable | The 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_unknown | Login restriction unknown | The 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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
model | query | string | No | The Bot: bot:<realm>/<id>, or a Bot id of the request’s realm. |
takeover | query | boolean | No | true takes over from the connection that controls the Bot’s voice now. |
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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. |
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"Response
Section titled “Response”101
Media type: none
The WebSocket upgrade is accepted, and the connection speaks the OpenAI Realtime protocol. The response has no body.
Error responses
Section titled “Error responses”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 codes
Section titled “Error codes”| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A 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_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
forbidden | Forbidden (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_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
model_not_found | No such model | No Bot has this id in a realm this login serves. | List the models and use one of their ids. |
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
voice_busy | Voice busy | Another connection controls this Bot’s voice. | Close the other connection, or connect with takeover=true to take over from it. |
bot_owned_elsewhere | Bot served by another agent | Another 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_limited | Too many requests | The 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_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
service_unavailable | Service unavailable | The 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_unknown | Login restriction unknown | The 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).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
model | string | Yes | The Bot to talk to, as …/models lists it: bot:<realm>/<id>. |
messages | array | Yes | The 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[].role | string | Yes | user, assistant, or an instruction role such as system or developer. |
messages[].content | string | array | Yes | The text, or a list of content parts. The last message takes text parts only. |
stream | boolean | No | true answers with Server-Sent Events. Default: false. |
stream_options | object | No | Stream options. |
stream_options.include_usage | boolean | No | Send a usage chunk at the end of the stream. |
max_tokens | integer | No | Output budget. It must be a positive integer; 64 or less marks a side request. |
max_completion_tokens | integer | No | Output budget. It wins over max_tokens when both are sent. |
user | string | No | The end user’s id. It is part of what makes a request the same request sent again. |
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?"}]}'Response
Section titled “Response”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 }}Error responses
Section titled “Error responses”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 codes
Section titled “Error codes”| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A 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_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
forbidden | Forbidden (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_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
model_not_found | No such model | No Bot has this id in a realm this login serves. | List the models and use one of their ids. |
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another 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_large | Payload too large | The 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_reused | Idempotency key reused | The 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_limited | Too many requests | The 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_exhausted | Too many remembered keys | The 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_busy | Bot busy | The Bot was answering other requests for the whole wait, so this message was not posted. | Send the request again in a moment. |
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
upstream_error | Side request cannot be capped | The 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_unavailable | Service unavailable | The 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_unknown | Login restriction unknown | The 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).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
model | string | Yes | The Bot to talk to, as …/models lists it: bot:<realm>/<id>. |
input | string | array | Yes | The message as a string, or a list of input items whose last message besides system and developer messages is a user message. |
instructions | string | No | Counts as the system prompt. |
stream | boolean | No | true answers with Server-Sent Events. Default: false. |
max_output_tokens | integer | No | Output budget. It must be a positive integer; 64 or less marks a side request. |
user | string | No | The end user’s id. It is part of what makes a request the same request sent again. |
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?"}'Response
Section titled “Response”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 }}Error responses
Section titled “Error responses”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 codes
Section titled “Error codes”| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A 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_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
forbidden | Forbidden (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_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
model_not_found | No such model | No Bot has this id in a realm this login serves. | List the models and use one of their ids. |
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
bot_owned_elsewhere | Bot served by another agent | Another 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_large | Payload too large | The 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_reused | Idempotency key reused | The 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_limited | Too many requests | The 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_exhausted | Too many remembered keys | The 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_busy | Bot busy | The Bot was answering other requests for the whole wait, so this message was not posted. | Send the request again in a moment. |
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
upstream_error | Side request cannot be capped | The 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_unavailable | Service unavailable | The 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_unknown | Login restriction unknown | The 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. |