# Agent: Bot URLs and compatible APIs **Page:** api/agent/bots/urls [Download Raw Markdown](./api/agent/bots/urls.md) --- # 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](/api/agent/bots/). ## 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) 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 `` 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/`, `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}` A GET of the Bot URL answers a short text page that starts with `This is the URL of Bot (bot:/)` 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 | Name | In | Type | Required | Description | |------|-----|------|----------|-------------| | `realm` | path | string | Yes | The realm. | | `bot` | path | string | Yes | The bot. | ```bash curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief" \ -H "Authorization: Bearer " ``` ### Response **200 (help page, text/plain)** Media type: application/json, text/plain ```text This is the URL of Bot Chief (bot:global/chief). Paste /v1 as the base URL of an OpenAI client (chat completions, responses, models). Paste as the base URL of an Anthropic client (Messages, models). Paste /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 **400** Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` **403** Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` **404** Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` **405** Media type: application/json ```json { "code": "method_not_allowed", "message": "this MCP server sends no stream and keeps no session: POST each request" } ``` **409** Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` **429** Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` **500** Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` **503** Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` ### 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}` 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 | 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. | ```bash curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief/mcp" \ -H "Authorization: Bearer " ``` ### Response **200 (help page, text/plain)** Media type: application/json, text/plain, text/event-stream ```text This is the URL of Bot Chief (bot:global/chief). Paste /v1 as the base URL of an OpenAI client (chat completions, responses, models). Paste as the base URL of an Anthropic client (Messages, models). Paste /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 **400** Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` **403** Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` **404** Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` **405** Media type: application/json ```json { "code": "method_not_allowed", "message": "this MCP server sends no stream and keeps no session: POST each request" } ``` **409** Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` **429** Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` **500** Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` **503** Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` ### 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}` 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 | Name | In | Type | Required | Description | |------|-----|------|----------|-------------| | `realm` | path | string | Yes | The realm. | | `bot` | path | string | Yes | The bot. | ### 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. | ```bash curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ --data '{"jsonrpc":"2.0","id":1,"method":"ping","params":{}}' ``` ### Response **200** Media type: application/json, text/event-stream ```json { "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 **400** Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` **403** Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` **404** Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` **409** Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` **413** Media type: application/json ```json { "code": "payload_too_large", "message": "request body exceeds the configured size limit" } ``` **422** Media type: application/json ```json { "code": "idempotency_key_reused", "message": "this Idempotency-Key was used for a different message" } ``` **429** Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` **500** Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` **503** Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` ### 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}` 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 | 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 | 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. | ```bash curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief/v1/chat/completions" \ -H "Authorization: Bearer " \ -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 **200** Media type: application/json, text/event-stream ```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 } } ``` 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 **400** Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` **403** Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` **404** Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` **409** Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` **413** Media type: application/json ```json { "code": "payload_too_large", "message": "request body exceeds the configured size limit" } ``` **422** Media type: application/json ```json { "code": "idempotency_key_reused", "message": "this Idempotency-Key was used for a different message" } ``` **429** Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` **500** Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` **502** Media type: application/json ```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 ```json { "code": "service_unavailable", "message": "service unavailable" } ``` ### 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}` 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 | Name | In | Type | Required | Description | |------|-----|------|----------|-------------| | `realm` | path | string | Yes | The realm. | | `bot` | path | string | Yes | The bot. | ```bash curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief" \ -H "Authorization: Bearer " ``` ### 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 **400** Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` **403** Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` **404** Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` **405** Media type: application/json ```json { "code": "method_not_allowed", "message": "this MCP server sends no stream and keeps no session: POST each request" } ``` **409** Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` **429** Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` **500** Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` **503** Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` ### 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}` 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 | Name | In | Type | Required | Description | |------|-----|------|----------|-------------| | `realm` | path | string | Yes | The realm. | | `bot` | path | string | Yes | The bot. | | `door` | path | string | Yes | The door. | ```bash curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/global/chief/mcp" \ -H "Authorization: Bearer " ``` ### 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 **400** Media type: application/json ```json { "code": "bad_request", "message": "invalid request" } ``` **403** Media type: application/json ```json { "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only" } ``` **404** Media type: application/json ```json { "code": "not_found", "message": "resource not found" } ``` **405** Media type: application/json ```json { "code": "method_not_allowed", "message": "this MCP server sends no stream and keeps no session: POST each request" } ``` **409** Media type: application/json ```json { "code": "realm_blocked", "message": "realm is blocked" } ``` **429** Media type: application/json ```json { "code": "rate_limited", "message": "request rate limit exceeded" } ``` **500** Media type: application/json ```json { "code": "internal_error", "message": "internal server error" } ``` **503** Media type: application/json ```json { "code": "service_unavailable", "message": "service unavailable" } ``` ### 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 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:/` (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` 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 | 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. | ```bash curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/compat/anthropic/v1/models" \ -H "x-api-key: " ``` ### Response **200** Media type: application/json ```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 **400** Media type: application/json ```json { "type": "error", "error": { "type": "invalid_request_error", "message": "invalid request", "code": "bad_request" } } ``` **403** Media type: application/json ```json { "type": "error", "error": { "type": "api_error", "message": "Hoody Kit programs are reached through their URLs only", "code": "forbidden" } } ``` **404** Media type: application/json ```json { "type": "error", "error": { "type": "not_found_error", "message": "resource not found", "code": "not_found" } } ``` **409** Media type: application/json ```json { "type": "error", "error": { "type": "api_error", "message": "realm is blocked", "code": "realm_blocked" } } ``` **429** Media type: application/json ```json { "type": "error", "error": { "type": "rate_limit_error", "message": "request rate limit exceeded", "code": "rate_limited" } } ``` **500** Media type: application/json ```json { "type": "error", "error": { "type": "api_error", "message": "internal server error", "code": "internal_error" } } ``` **503** Media type: application/json ```json { "type": "error", "error": { "type": "overloaded_error", "message": "service unavailable", "code": "service_unavailable" } } ``` ### 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}` 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 | 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. | ```bash 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: " ``` ### Response **200** Media type: application/json ```json { "type": "model", "id": "bot:global/chief", "display_name": "Chief", "created_at": "2026-10-08T10:30:00Z" } ``` ### Error responses **400** Media type: application/json ```json { "type": "error", "error": { "type": "invalid_request_error", "message": "invalid request", "code": "bad_request" } } ``` **403** Media type: application/json ```json { "type": "error", "error": { "type": "api_error", "message": "Hoody Kit programs are reached through their URLs only", "code": "forbidden" } } ``` **404** Media type: application/json ```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 ```json { "type": "error", "error": { "type": "api_error", "message": "realm is blocked", "code": "realm_blocked" } } ``` **429** Media type: application/json ```json { "type": "error", "error": { "type": "rate_limit_error", "message": "request rate limit exceeded", "code": "rate_limited" } } ``` **500** Media type: application/json ```json { "type": "error", "error": { "type": "api_error", "message": "internal server error", "code": "internal_error" } } ``` **503** Media type: application/json ```json { "type": "error", "error": { "type": "overloaded_error", "message": "service unavailable", "code": "service_unavailable" } } ``` ### 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` 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 | 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 | Name | Type | Required | Description | |------|------|----------|-------------| | `model` | string | Yes | The Bot to talk to, as `…/models` lists it: `bot:/`. | | `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. | ```bash 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: " \ -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 **200** Media type: application/json ```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 **400** Media type: application/json ```json { "type": "error", "error": { "type": "invalid_request_error", "message": "invalid request", "code": "bad_request" } } ``` **403** Media type: application/json ```json { "type": "error", "error": { "type": "api_error", "message": "Hoody Kit programs are reached through their URLs only", "code": "forbidden" } } ``` **404** Media type: application/json ```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 ```json { "type": "error", "error": { "type": "api_error", "message": "realm is blocked", "code": "realm_blocked" } } ``` **413** Media type: application/json ```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 ```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 ```json { "type": "error", "error": { "type": "rate_limit_error", "message": "request rate limit exceeded", "code": "rate_limited" } } ``` **500** Media type: application/json ```json { "type": "error", "error": { "type": "api_error", "message": "internal server error", "code": "internal_error" } } ``` **502** Media type: application/json ```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 ```json { "type": "error", "error": { "type": "overloaded_error", "message": "service unavailable", "code": "service_unavailable" } } ``` ### 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 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:/` (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` 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 | 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. | ```bash curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/compat/openai/v1/models" \ -H "Authorization: Bearer " ``` ### Response **200** Media type: application/json ```json { "object": "list", "data": [ { "id": "bot:global/chief", "object": "model", "created": 1762533000, "owned_by": "hoody" } ] } ``` ### Error responses **400** Media type: application/json ```json { "error": { "message": "invalid request", "type": "invalid_request_error", "param": null, "code": "bad_request" } } ``` **403** Media type: application/json ```json { "error": { "message": "Hoody Kit programs are reached through their URLs only", "type": "api_error", "param": null, "code": "forbidden" } } ``` **404** Media type: application/json ```json { "error": { "message": "resource not found", "type": "not_found_error", "param": null, "code": "not_found" } } ``` **409** Media type: application/json ```json { "error": { "message": "realm is blocked", "type": "api_error", "param": null, "code": "realm_blocked" } } ``` **429** Media type: application/json ```json { "error": { "message": "request rate limit exceeded", "type": "rate_limit_error", "param": null, "code": "rate_limited" } } ``` **500** Media type: application/json ```json { "error": { "message": "internal server error", "type": "api_error", "param": null, "code": "internal_error" } } ``` **503** Media type: application/json ```json { "error": { "message": "service unavailable", "type": "api_error", "param": null, "code": "service_unavailable" } } ``` ### 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}` 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 | 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. | ```bash 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 " ``` ### Response **200** Media type: application/json ```json { "id": "bot:global/chief", "object": "model", "created": 1762533000, "owned_by": "hoody" } ``` ### Error responses **400** Media type: application/json ```json { "error": { "message": "invalid request", "type": "invalid_request_error", "param": null, "code": "bad_request" } } ``` **403** Media type: application/json ```json { "error": { "message": "Hoody Kit programs are reached through their URLs only", "type": "api_error", "param": null, "code": "forbidden" } } ``` **404** Media type: application/json ```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 ```json { "error": { "message": "realm is blocked", "type": "api_error", "param": null, "code": "realm_blocked" } } ``` **429** Media type: application/json ```json { "error": { "message": "request rate limit exceeded", "type": "rate_limit_error", "param": null, "code": "rate_limited" } } ``` **500** Media type: application/json ```json { "error": { "message": "internal server error", "type": "api_error", "param": null, "code": "internal_error" } } ``` **503** Media type: application/json ```json { "error": { "message": "service unavailable", "type": "api_error", "param": null, "code": "service_unavailable" } } ``` ### 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` Opens a voice conversation with the Bot. `?model=` names the Bot: `bot:/`, 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///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 | Name | In | Type | Required | Description | |------|-----|------|----------|-------------| | `model` | query | string | No | The Bot: `bot:/`, 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. | ```bash 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 **101** Media type: none The WebSocket upgrade is accepted, and the connection speaks the OpenAI Realtime protocol. The response has no body. ### Error responses **400** Media type: application/json ```json { "error": { "message": "invalid request", "type": "invalid_request_error", "param": null, "code": "bad_request" } } ``` **403** Media type: application/json ```json { "error": { "message": "Hoody Kit programs are reached through their URLs only", "type": "api_error", "param": null, "code": "forbidden" } } ``` **404** Media type: application/json ```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 ```json { "error": { "message": "another voice connection controls this Bot", "type": "api_error", "param": null, "code": "voice_busy" } } ``` **429** Media type: application/json ```json { "error": { "message": "request rate limit exceeded", "type": "rate_limit_error", "param": null, "code": "rate_limited" } } ``` **500** Media type: application/json ```json { "error": { "message": "internal server error", "type": "api_error", "param": null, "code": "internal_error" } } ``` **503** Media type: application/json ```json { "error": { "message": "service unavailable", "type": "api_error", "param": null, "code": "service_unavailable" } } ``` ### 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` 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 | 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 | Name | Type | Required | Description | |------|------|----------|-------------| | `model` | string | Yes | The Bot to talk to, as `…/models` lists it: `bot:/`. | | `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. | ```bash curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/compat/openai/v1/chat/completions" \ -H "Authorization: Bearer " \ -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 **200** Media type: application/json ```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 **400** Media type: application/json ```json { "error": { "message": "invalid request", "type": "invalid_request_error", "param": null, "code": "bad_request" } } ``` **403** Media type: application/json ```json { "error": { "message": "Hoody Kit programs are reached through their URLs only", "type": "api_error", "param": null, "code": "forbidden" } } ``` **404** Media type: application/json ```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 ```json { "error": { "message": "realm is blocked", "type": "api_error", "param": null, "code": "realm_blocked" } } ``` **413** Media type: application/json ```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 ```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 ```json { "error": { "message": "request rate limit exceeded", "type": "rate_limit_error", "param": null, "code": "rate_limited" } } ``` **500** Media type: application/json ```json { "error": { "message": "internal server error", "type": "api_error", "param": null, "code": "internal_error" } } ``` **502** Media type: application/json ```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 ```json { "error": { "message": "service unavailable", "type": "api_error", "param": null, "code": "service_unavailable" } } ``` ### 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` 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 | 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 | Name | Type | Required | Description | |------|------|----------|-------------| | `model` | string | Yes | The Bot to talk to, as `…/models` lists it: `bot:/`. | | `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. | ```bash curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/compat/openai/v1/responses" \ -H "Authorization: Bearer " \ -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 **200** Media type: application/json ```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 **400** Media type: application/json ```json { "error": { "message": "invalid request", "type": "invalid_request_error", "param": null, "code": "bad_request" } } ``` **403** Media type: application/json ```json { "error": { "message": "Hoody Kit programs are reached through their URLs only", "type": "api_error", "param": null, "code": "forbidden" } } ``` **404** Media type: application/json ```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 ```json { "error": { "message": "realm is blocked", "type": "api_error", "param": null, "code": "realm_blocked" } } ``` **413** Media type: application/json ```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 ```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 ```json { "error": { "message": "request rate limit exceeded", "type": "rate_limit_error", "param": null, "code": "rate_limited" } } ``` **500** Media type: application/json ```json { "error": { "message": "internal server error", "type": "api_error", "param": null, "code": "internal_error" } } ``` **502** Media type: application/json ```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 ```json { "error": { "message": "service unavailable", "type": "api_error", "param": null, "code": "service_unavailable" } } ``` ### 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. |