Agent: Models & Providers

This page documents the agent’s model and provider registry, plus the credential-management endpoints used to bind LLM providers. Use these routes to enumerate bindable models and providers, to read and manage a provider’s auth status (API key vs. OAuth), to drive an OAuth login flow, and to maintain a pooled OAuth account pool per provider. All routes live under the agent service on the container host https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com.

Models

`GET /api/v1/agent/models`

Returns the merged model catalogue: every catalogued provider model alongside every selectable fusion composite (fusion/<slug>). Each entry carries source: "provider" or source: "fusion". A composite’s context_window is the minimum across its catalogued members, and composites carry no per-token price. Fusion composites are resolved against the cwd/config_dir scope honored by the X-Hoody-Cwd / X-Hoody-Config-Dir headers; only selectable composites appear — broken composites are excluded.

Parameters

Name	In	Type	Required	Description
`page`	query	integer	No	1-based page number for pagination.
`limit`	query	integer	No	Maximum items per page (0 = no pagination).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope: the `.hoody` project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override selecting which on-disk `.hoody` install a stateless read/write resolves.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id (also accepted as `?realm=`). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header (read only when the header is absent).

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/models?page=1&limit=50" \
  -H "Authorization: Bearer <HOODY_TOKEN>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.models.listModelsIterator({ page: 1, limit: 50 });

{
  "items": [
    {
      "spec": "anthropic/claude-opus-4-8",
      "source": "provider",
      "display_name": "Claude Opus 4.8",
      "context_window": 200000,
      "output_limit": 32000,
      "reasoning": true,
      "price_input_per_token": 0.000015,
      "price_output_per_token": 0.000075
    },
    {
      "spec": "fusion/team-ensemble",
      "source": "fusion",
      "method": "majority",
      "members": [
        "anthropic/claude-opus-4-8",
        "openai/gpt-5",
        "google/gemini-2.5-pro"
      ],
      "context_window": 200000
    }
  ],
  "meta": {
    "total": 312,
    "page": 1,
    "limit": 50
  }
}

{
  "code": "bad_request",
  "message": "invalid page parameter"
}

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 realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

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

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

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

Error Code	Title	Description	Resolution
`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.

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

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

`GET /api/v1/agent/models/{spec}`

Returns one catalogued model by its full spec (e.g. anthropic/claude-opus-4-8) or a fusion composite by its fusion/<slug> spec. The spec itself contains a slash, so it is passed URL-encoded or as the trailing path segment (models.get). A per-request realm header (and X-Hoody-Container) returns 400 realm_scope_unsupported.

Parameters

Name	In	Type	Required	Description
`spec`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope: the `.hoody` project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override selecting which on-disk `.hoody` install a stateless read/write resolves.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id. Rejected (400 `realm_scope_unsupported`).
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/models/anthropic%2Fclaude-opus-4-8" \
  -H "Authorization: Bearer <HOODY_TOKEN>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.models.getModel('anthropic/claude-opus-4-8');

{
  "spec": "anthropic/claude-opus-4-8",
  "source": "provider",
  "display_name": "Claude Opus 4.8",
  "context_window": 200000,
  "output_limit": 32000,
  "reasoning": true,
  "price_input_per_token": 0.000015,
  "price_output_per_token": 0.000075
}

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

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 realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "no such model"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

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

Error Code	Title	Description	Resolution
`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.

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

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

Providers

`GET /api/v1/agent/providers`

Lists every catalogued LLM provider (id, display name, model prefix, wire format, model count) from the merged providers.json catalogue. The catalogue is process-wide with no realm dimension, so a per-request realm header returns 400 realm_scope_unsupported.

Parameters

Name	In	Type	Required	Description
`page`	query	integer	No	1-based page number for pagination.
`limit`	query	integer	No	Maximum items per page (0 = no pagination).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container. Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400 `realm_scope_unsupported`) on global-no-realm routes.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/providers?page=1&limit=50" \
  -H "Authorization: Bearer <HOODY_TOKEN>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.models.listProvidersIterator({ page: 1, limit: 50 });

{
  "items": [
    {
      "id": "anthropic",
      "display_name": "Anthropic",
      "prefix": "anthropic",
      "wire_format": "anthropic-native",
      "model_count": 18
    },
    {
      "id": "openai",
      "display_name": "OpenAI",
      "prefix": "openai",
      "wire_format": "openai-native",
      "model_count": 24
    }
  ],
  "meta": {
    "total": 14,
    "page": 1,
    "limit": 50
  }
}

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

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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

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

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

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

Error Code	Title	Description	Resolution
`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.

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

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

`GET /api/v1/agent/providers/{id}`

Returns one provider’s metadata plus its full catalogued model list (providers.get).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container. Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400 `realm_scope_unsupported`).
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/providers/anthropic" \
  -H "Authorization: Bearer <HOODY_TOKEN>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.models.getProvider('anthropic');

{
  "id": "anthropic",
  "display_name": "Anthropic",
  "prefix": "anthropic",
  "wire_format": "anthropic-native",
  "passwordless": false,
  "login_id": "anthropic-prod",
  "models": [
    "anthropic/claude-opus-4-8",
    "anthropic/claude-sonnet-4-5",
    "anthropic/claude-haiku-4-5"
  ]
}

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

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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "no such provider"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

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

Error Code	Title	Description	Resolution
`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.

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

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

Provider auth status

`GET /api/v1/agent/providers/{id}/auth`

Reports a provider’s stored-credential state: whether an API key or OAuth login is stored, the effective default method, the passwordless flag, and the secret-free OAuth account pool. Any stored API key is surfaced as a 10-character prefix only — the full key is never returned.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container. Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400 `realm_scope_unsupported`).
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/providers/anthropic/auth" \
  -H "Authorization: Bearer <HOODY_TOKEN>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.models.getProviderAuth('anthropic');

{
  "id": "anthropic",
  "default": "api_key",
  "passwordless": false,
  "api_key": {
    "stored": true,
    "prefix": "sk-ant-api"
  },
  "oauth": {
    "supported": true,
    "stored": false
  },
  "oauth_accounts": []
}

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

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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "no such provider"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

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

Error Code	Title	Description	Resolution
`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.

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

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

OAuth account pool

`GET /api/v1/agent/providers/{id}/auth/accounts`

Lists the secret-free OAuth account pool for a provider: key, label, active flag, cooldown — never a token. Returns 422 oauth_unsupported when the provider has no OAuth flow.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`page`	query	integer	No	1-based page number for pagination.
`limit`	query	integer	No	Maximum items per page (0 = no pagination).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container. Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400 `realm_scope_unsupported`).
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/providers/anthropic/auth/accounts" \
  -H "Authorization: Bearer <HOODY_TOKEN>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.models.listProviderAccountsIterator('anthropic');

{
  "items": [
    {
      "key": "acct_personal",
      "label": "personal",
      "active": true,
      "cooldown_until": null
    },
    {
      "key": "acct_work",
      "label": "work",
      "active": false,
      "cooldown_until": "2026-02-01T12:00:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 50
  }
}

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

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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	Forbidden — the request was refused by the server’s admin gate.	Run the daemon with socket auth (`--auth-token-path`) and no separate admin capability so its own gate allows HTTP requests forwarded from the gateway.
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "oauth_unsupported",
  "message": "provider does not support OAuth login"
}

Error Code	Title	Description	Resolution
`oauth_unsupported`	OAuth not supported	The provider has no OAuth login flow (no login id), so an OAuth start/poll/submit/logout or a default=oauth promotion cannot be honored.	Use an API key for this provider (`PUT /providers/{id}/auth/api-key`), or pick a provider that supports OAuth.

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

Error Code	Title	Description	Resolution
`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.

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

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

`POST /api/v1/agent/providers/{id}/auth/accounts`

Begins an OAuth login that adds to the provider’s account pool. Returns a {job_id}; drive it with the same poll/submit endpoints used by startProviderOAuth. Returns 422 oauth_unsupported when the provider has no OAuth flow.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container. Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400 `realm_scope_unsupported`).
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

This endpoint accepts no documented body fields.

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/providers/anthropic/auth/accounts" \
  -H "Authorization: Bearer <HOODY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.models.addProviderAccount('anthropic', {});

{
  "job_id": "oauth-job-7f3a9b",
  "verification_uri": "https://provider.example.com/device",
  "user_code": "ABCD-1234"
}

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

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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	Forbidden — the request was refused by the server’s admin gate.	Run the daemon with socket auth (`--auth-token-path`) and no separate admin capability.
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "no such provider"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.
`job_not_found`	Job not found	The referenced OAuth login job does not exist or has expired.	Restart the flow with `POST /providers/{id}/auth/oauth` and drive the new job id.

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

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (MaxBodyBytes).	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

{
  "code": "oauth_unsupported",
  "message": "provider does not support OAuth login"
}

Error Code	Title	Description	Resolution
`oauth_unsupported`	OAuth not supported	The provider has no OAuth login flow.	Use an API key for this provider (`PUT /providers/{id}/auth/api-key`), or pick a provider that supports OAuth.

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

Error Code	Title	Description	Resolution
`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.

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

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

`PUT /api/v1/agent/providers/{id}/auth/accounts/{key}/active`

Makes one pooled OAuth account active for a provider. The {key} path value names the account; the trailing /active sub-resource names the activation verb. Returns the resulting secret-free account pool. Returns 422 oauth_unsupported.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`key`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container. Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400 `realm_scope_unsupported`).
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

This endpoint accepts no documented body fields.

curl -X PUT "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/providers/anthropic/auth/accounts/acct_work/active" \
  -H "Authorization: Bearer <HOODY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.models.setProviderAccountActive('anthropic', 'acct_work', {});

{
  "accounts": [
    {
      "key": "acct_personal",
      "label": "personal",
      "active": false,
      "cooldown_until": null
    },
    {
      "key": "acct_work",
      "label": "work",
      "active": true,
      "cooldown_until": "2026-02-01T12:00:00Z"
    }
  ]
}

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

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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	Forbidden — the request was refused by the server’s admin gate.	Run the daemon with socket auth (`--auth-token-path`) and no separate admin capability.
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "no such account"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

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

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (MaxBodyBytes).	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

{
  "code": "oauth_unsupported",
  "message": "provider does not support OAuth login"
}

Error Code	Title	Description	Resolution
`oauth_unsupported`	OAuth not supported	The provider has no OAuth login flow.	Use an API key for this provider (`PUT /providers/{id}/auth/api-key`), or pick a provider that supports OAuth.

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

Error Code	Title	Description	Resolution
`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.

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

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

`DELETE /api/v1/agent/providers/{id}/auth/accounts/{key}`

Drops one pooled OAuth account for a provider. The {key} path value names the account. Returns the resulting secret-free account pool. Returns 422 oauth_unsupported.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`key`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container. Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400 `realm_scope_unsupported`).
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

curl -X DELETE "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/providers/anthropic/auth/accounts/acct_work" \
  -H "Authorization: Bearer <HOODY_TOKEN>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.models.removeProviderAccount('anthropic', 'acct_work');

{
  "accounts": [
    {
      "key": "acct_personal",
      "label": "personal",
      "active": true,
      "cooldown_until": null
    }
  ]
}

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

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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	Forbidden — the request was refused by the server’s admin gate.	Run the daemon with socket auth (`--auth-token-path`) and no separate admin capability.
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "no such account"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "oauth_unsupported",
  "message": "provider does not support OAuth login"
}

Error Code	Title	Description	Resolution
`oauth_unsupported`	OAuth not supported	The provider has no OAuth login flow.	Use an API key for this provider (`PUT /providers/{id}/auth/api-key`), or pick a provider that supports OAuth.

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

Error Code	Title	Description	Resolution
`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.

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

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

`POST /api/v1/agent/providers/{id}/auth/oauth`

Begins an interactive OAuth login for a provider and returns {success, job_id, verification_uri, user_code?}. Drive the flow with GET .../oauth/{job} (poll) and, for a manual/PKCE code, POST .../oauth/{job}/code (submit). The job carries only the non-secret verification URL and user code — never a token. Returns 422 oauth_unsupported.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container. Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400 `realm_scope_unsupported`).
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Name	Type	Required	Description
`add_account`	boolean	No	When `true`, the login ADDS to the provider’s OAuth account pool (`LoginAddAccount`) instead of replacing the primary login.

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/providers/anthropic/auth/oauth" \
  -H "Authorization: Bearer <HOODY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.models.startProviderOAuth('anthropic', {});

{
  "job_id": "oauth-job-7f3a9b",
  "verification_uri": "https://provider.example.com/device",
  "user_code": "ABCD-1234"
}

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

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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	Forbidden — the request was refused by the server’s admin gate.	Run the daemon with socket auth (`--auth-token-path`) and no separate admin capability.
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "no such provider"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.
`job_not_found`	Job not found	The referenced OAuth login job does not exist or has expired.	Restart the flow with `POST /providers/{id}/auth/oauth` and drive the new job id.

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

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (MaxBodyBytes).	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

{
  "code": "oauth_unsupported",
  "message": "provider does not support OAuth login"
}

Error Code	Title	Description	Resolution
`oauth_unsupported`	OAuth not supported	The provider has no OAuth login flow.	Use an API key for this provider (`PUT /providers/{id}/auth/api-key`), or pick a provider that supports OAuth.

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

Error Code	Title	Description	Resolution
`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.

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

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

`GET /api/v1/agent/providers/{id}/auth/oauth/{job}`

Polls an in-flight OAuth login job. Reports state: "pending" until the user authorizes, then state: "complete" (with the now-current secret-free auth status) or state: "error" (with a scrubbed error message).

Returns 404 job_not_found when the job is unknown or expired; 422 oauth_unsupported when the provider has no OAuth flow.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`job`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container. Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400 `realm_scope_unsupported`).
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/providers/anthropic/auth/oauth/oauth-job-7f3a9b" \
  -H "Authorization: Bearer <HOODY_TOKEN>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.models.pollProviderOAuth('anthropic', 'oauth-job-7f3a9b');

{
  "state": "pending",
  "verification_uri": "https://provider.example.com/device",
  "user_code": "ABCD-1234",
  "needs_code": false
}

{
  "state": "complete",
  "auth": {
    "id": "anthropic",
    "default": "oauth",
    "passwordless": false,
    "oauth": { "supported": true, "stored": true }
  }
}

{
  "state": "error",
  "error": "user denied authorization"
}

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

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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	Forbidden — the request was refused by the server’s admin gate.	Run the daemon with socket auth (`--auth-token-path`) and no separate admin capability.
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "job_not_found",
  "message": "no such OAuth job (it may have expired)"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.
`job_not_found`	Job not found	The referenced OAuth login job does not exist or has expired (idle past its TTL, or the daemon restarted).	Restart the flow with `POST /providers/{id}/auth/oauth` and drive the new job id.

{
  "code": "oauth_unsupported",
  "message": "provider does not support OAuth login"
}

Error Code	Title	Description	Resolution
`oauth_unsupported`	OAuth not supported	The provider has no OAuth login flow.	Use an API key for this provider (`PUT /providers/{id}/auth/api-key`), or pick a provider that supports OAuth.

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

Error Code	Title	Description	Resolution
`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.

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

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

`POST /api/v1/agent/providers/{id}/auth/oauth/{job}/code`

Supplies the authorization code (or full redirect URL) a blocked OAuth flow is waiting for — the explicit code-exchange step for manual-paste / PKCE flows. Idempotent-safe: a second submit on an already-fed job is a no-op (submitted: false). Returns 404 job_not_found when the job is unknown or expired.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`job`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container. Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400 `realm_scope_unsupported`).
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Name	Type	Required	Description
`code`	string	Yes	The authorization code (or the full redirect URL) to complete the exchange.

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/providers/anthropic/auth/oauth/oauth-job-7f3a9b/code" \
  -H "Authorization: Bearer <HOODY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"code": "auth-code-xyz123"}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.models.submitProviderOAuthCode('anthropic', 'oauth-job-7f3a9b', {
  code: 'auth-code-xyz123',
});

{
  "submitted": true,
  "message": "code accepted"
}

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

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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	Forbidden — the request was refused by the server’s admin gate.	Run the daemon with socket auth (`--auth-token-path`) and no separate admin capability.
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "job_not_found",
  "message": "no such OAuth job (it may have expired)"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.
`job_not_found`	Job not found	The referenced OAuth login job does not exist or has expired.	Restart the flow with `POST /providers/{id}/auth/oauth` and drive the new job id.

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

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (MaxBodyBytes).	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

{
  "code": "oauth_unsupported",
  "message": "provider does not support OAuth login"
}

Error Code	Title	Description	Resolution
`oauth_unsupported`	OAuth not supported	The provider has no OAuth login flow.	Use an API key for this provider (`PUT /providers/{id}/auth/api-key`), or pick a provider that supports OAuth.

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

Error Code	Title	Description	Resolution
`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.

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

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

`DELETE /api/v1/agent/providers/{id}/auth/oauth`

Removes a provider’s stored OAuth credentials. Idempotent. Returns the resulting secret-free auth status. Returns 422 oauth_unsupported when the provider has no OAuth flow.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container. Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400 `realm_scope_unsupported`).
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

curl -X DELETE "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/providers/anthropic/auth/oauth" \
  -H "Authorization: Bearer <HOODY_TOKEN>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.models.logoutProviderOAuth('anthropic');

{
  "auth": {
    "id": "anthropic",
    "default": "api_key",
    "passwordless": false,
    "api_key": { "stored": true, "prefix": "sk-ant-api" },
    "oauth": { "supported": true, "stored": false }
  }
}

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

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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	Forbidden — the request was refused by the server’s admin gate.	Run the daemon with socket auth (`--auth-token-path`) and no separate admin capability.
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "no such provider"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.
`job_not_found`	Job not found	The referenced OAuth login job does not exist or has expired.	Restart the flow with `POST /providers/{id}/auth/oauth` and drive the new job id.

{
  "code": "oauth_unsupported",
  "message": "provider does not support OAuth login"
}

Error Code	Title	Description	Resolution
`oauth_unsupported`	OAuth not supported	The provider has no OAuth login flow.	Use an API key for this provider (`PUT /providers/{id}/auth/api-key`), or pick a provider that supports OAuth.

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

Error Code	Title	Description	Resolution
`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.

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

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

API key

`PUT /api/v1/agent/providers/{id}/auth/api-key`

Stores a provider’s API key in the 0600 atomic ~/.hoody/.env keychainless store. The key is written 0600-atomic and is never returned — the reply carries only the secret-free auth status (10-character prefix). Returns 422 auth_method_unsupported for a passwordless provider.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container. Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400 `realm_scope_unsupported`).
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Name	Type	Required	Description
`api_key`	string	Yes	The provider API key. Stored in the 0600 `~/.hoody/.env` store; the reply echoes only a prefix.

curl -X PUT "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/providers/anthropic/auth/api-key" \
  -H "Authorization: Bearer <HOODY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "sk-ant-api03-REPLACE_ME"}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.models.setProviderAPIKey('anthropic', {
  api_key: 'sk-ant-api03-REPLACE_ME',
});

{
  "auth": {
    "id": "anthropic",
    "default": "api_key",
    "passwordless": false,
    "api_key": { "stored": true, "prefix": "sk-ant-api" }
  }
}

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

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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	Forbidden — the request was refused by the server’s admin gate.	Run the daemon with socket auth (`--auth-token-path`) and no separate admin capability.
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "no such provider"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

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

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (MaxBodyBytes).	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

{
  "code": "auth_method_unsupported",
  "message": "provider is passwordless (no API key method)"
}

Error Code	Title	Description	Resolution
`oauth_unsupported`	OAuth not supported	The provider has no OAuth login flow.	Use an API key for this provider, or pick a provider that supports OAuth.
`auth_method_unsupported`	Auth method unsupported	The requested credential method is not available for this provider (e.g. an API-key default on a passwordless provider).	Pick a method the provider supports; a passwordless provider needs no default.
`credential_not_stored`	Credential not stored	The default method cannot be promoted because no credential of that kind is stored for the provider yet.	Store the credential first (`PUT /providers/{id}/auth/api-key`, or complete `POST /providers/{id}/auth/oauth`), then set the default.

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

Error Code	Title	Description	Resolution
`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.

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

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

`DELETE /api/v1/agent/providers/{id}/auth/api-key`

Removes a provider’s stored API key and its default-method marker. Idempotent. Returns the resulting secret-free auth status.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container. Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400 `realm_scope_unsupported`).
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

curl -X DELETE "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/providers/anthropic/auth/api-key" \
  -H "Authorization: Bearer <HOODY_TOKEN>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.models.deleteProviderAPIKey('anthropic');

{
  "auth": {
    "id": "anthropic",
    "default": null,
    "passwordless": false,
    "api_key": { "stored": false, "prefix": null },
    "oauth": { "supported": true, "stored": false }
  }
}

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

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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	Forbidden — the request was refused by the server’s admin gate.	Run the daemon with socket auth (`--auth-token-path`) and no separate admin capability.
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "no such provider"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "credential_not_stored",
  "message": "no API key is stored for this provider"
}

Error Code	Title	Description	Resolution
`oauth_unsupported`	OAuth not supported	The provider has no OAuth login flow.	Use an API key for this provider, or pick a provider that supports OAuth.
`auth_method_unsupported`	Auth method unsupported	The requested credential method is not available for this provider.	Pick a method the provider supports; a passwordless provider needs no default.
`credential_not_stored`	Credential not stored	The default method cannot be promoted because no credential of that kind is stored for the provider yet.	Store the credential first (`PUT /providers/{id}/auth/api-key`, or complete `POST /providers/{id}/auth/oauth`), then set the default.

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

Error Code	Title	Description	Resolution
`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.

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

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

Default credential method

`PUT /api/v1/agent/providers/{id}/auth/default`

Sets the effective default credential method for a provider: api_key or oauth. The daemon validates the method against the provider’s capabilities and that a credential of that kind is actually stored (else 422). Returns 422 oauth_unsupported / auth_method_unsupported / credential_not_stored.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container. Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected (400 `realm_scope_unsupported`).
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header.

Request Body

Name	Type	Required	Description
`default`	string	Yes	The default method: `"api_key"` or `"oauth"`. Must be a method the provider supports AND has a stored credential for.

curl -X PUT "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/providers/anthropic/auth/default" \
  -H "Authorization: Bearer <HOODY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"default": "api_key"}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.models.setProviderDefault('anthropic', {
  default: 'api_key',
});

{
  "auth": {
    "id": "anthropic",
    "default": "api_key",
    "passwordless": false,
    "api_key": { "stored": true, "prefix": "sk-ant-api" }
  }
}

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

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 realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	Forbidden — the request was refused by the server’s admin gate.	Run the daemon with socket auth (`--auth-token-path`) and no separate admin capability.
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "no such provider"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

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

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (MaxBodyBytes).	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

{
  "code": "credential_not_stored",
  "message": "no API key is stored for this provider"
}

Error Code	Title	Description	Resolution
`oauth_unsupported`	OAuth not supported	The provider has no OAuth login flow.	Use an API key for this provider, or pick a provider that supports OAuth.
`auth_method_unsupported`	Auth method unsupported	The requested credential method is not available for this provider (e.g. an API-key default on a passwordless provider).	Pick a method the provider supports; a passwordless provider needs no default.
`credential_not_stored`	Credential not stored	The default method cannot be promoted because no credential of that kind is stored for the provider yet.	Store the credential first (`PUT /providers/{id}/auth/api-key`, or complete `POST /providers/{id}/auth/oauth`), then set the default.

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

Error Code	Title	Description	Resolution
`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.

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

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.