--- title: Management API description: Authentication, errors, and endpoint reference for the opencodex control plane. --- The Management API is opencodex's control plane. The dashboard at `http://localhost:10100` is one client of it; headless `ocx` provider, model, combo, account, settings, diagnostics, and lifecycle commands are clients too. The API is available only while the proxy is running. Use the [Web Dashboard](/guides/web-dashboard/) for an interactive client, or this reference when building automation. Persistent values ultimately follow [Configuration](/reference/configuration/). ## Authentication model The Management API has its own admin credential, independent of data-plane API keys. At startup, opencodex resolves it in this order: 1. `OPENCODEX_ADMIN_AUTH_TOKEN`, when set. 2. A generated `ocx_admin_*` token in a hardened secret file. The file-backed token is accepted only after its directory and file permissions or ACLs have been hardened. If that cannot be guaranteed, management authentication fails closed and the API returns 503 until an environment token is supplied or the file state is repaired. Send the admin token in either form: ```http X-OpenCodex-API-Key: ``` ```http Authorization: Bearer ``` :::caution The admin token must differ from every data-plane credential. Startup rejects a management credential that conflicts with a proxy admission key. Do not put the admin token in Codex, Claude Code, or another model client; it authorizes control-plane mutations. ::: ### Loopback dashboard sessions On a loopback bind, the dashboard bootstrap can receive a short-lived `ocx_session_*` credential. Each session lasts five minutes and is bound to the exact dashboard origin. Safe requests must match that origin. Unsafe methods also require the browser `Origin` and the session's CSRF token. When data-plane authentication is required, which includes remote binds, the loopback bootstrap does not mint a session. A remote dashboard gets a 12-hour session only through a trusted Tailscale identity (`remoteGui.allowedTailscaleUsers` on the Tailscale management ingress) or a one-use pairing grant; each authorized request extends it. Otherwise a remote operator authenticates with the raw admin token, and the dashboard asks for it again after a reload because the session lives only in page memory. See [Remote hub](/guides/remote-hub/). ## Common errors All endpoint rows below inherit these boundary errors. The “Notable errors” column lists additional route-specific results rather than repeating this table. | Status | Type or code | Meaning | | --- | --- | --- | | 401 | `opencodex admin token required` | The admin token or GUI session is missing, invalid, expired, origin-mismatched, or missing CSRF evidence | | 403 | `cross-origin request blocked` | The request origin is outside the management allowlist | | 403 | `code: "remember_requires_direct_origin"` | `POST /api/session/remember` only: this dashboard address cannot hold a remembered device (for example a standalone dashboard behind a TLS-terminating proxy without `dashboardTrustedProxy`, or a proxied request that did not come from one of its `proxyAddresses` or whose host, scheme or `Origin` does not match its `origin`); sign in without Remember. The `error` text is `cross-origin request blocked` when the origin check refuses the request, and `Remember requires a direct HTTPS dashboard (or loopback) and matching Origin` when the origin check allows the request but the route still refuses it, for example because the address is not a direct HTTPS, loopback or configured-proxy dashboard or no matching `Origin` header was sent; match on `code` | | 404 | `not_found` | No management route matched the method and path | | 413 | `request body too large` | A POST, PUT, or PATCH body exceeds the 2 MiB management limit | | 503 | `management API unavailable` | Admin credential initialization or hardening is unavailable | | 503 | `oauth_mutation_busy` | Another OAuth credential mutation holds the writer; response includes `Retry-After: 1` | | 503 | `catalog_busy` | Catalog gathering is already at capacity; response includes `Retry-After: 1` | ## Endpoint matrix ### Agent and client settings | Method and path | Purpose | Notable errors | | --- | --- | --- | | `GET, PUT /api/v2` | Read or change native multi-agent v2 mode and thread settings | 400 invalid settings; 502 transition or persistence failure | | `GET, PUT /api/injection-model` | Read or set the injected sub-agent model, effort, prompt, and guidance settings | 400 invalid model, effort, or body | | `POST /api/injection-model/suggest` | Size a described delegated workload and propose a delegation model and effort without writing | 400 invalid work or model; 409 no sizing model | | `GET, PUT /api/effort-caps` | Read or set global and sub-agent reasoning-effort ceilings | 400 invalid ladder value | | `GET, PUT /api/subagent-models` | Read or order the models advertised to sub-agents | 400 invalid list or more than five models | | `GET, PUT /api/subagent-model-fallback` | Read or set the ordered fallback chain and poll interval | 400 invalid list or poll interval | | `GET /api/grok` | Read Grok managed-config status and candidate models | 400 status read failure | | `PUT /api/grok/selection` | Persist the excluded Grok models | 400 invalid or oversized selection | | `POST /api/grok/apply` | Apply persisted Grok configuration through the managed sync | 409 `grok_apply_busy`; 400/500 apply failure | | `GET /api/grok/reset-coupons?accountId=...` | Read remaining Grok billing reset tokens and validity windows for the active or specified xAI account | 400 missing account; 401 unauthenticated; 502 upstream gRPC-Web error | | `POST /api/grok/reset-coupons/consume` | Redeem an eligible reset coupon. Body `{ accountId?, tokenId?, operationId? }`. Optional `operationId` (UUIDv4) makes redemption idempotent: repeating the same ID replays the durable result without double-redemption. | 400 invalid JSON/UUID; 401 unauthenticated; 409 `operation_id_owned_by_another_account` / `coupon_unavailable` / `operation_token_mismatch` / `operation_state_changed` / `attempt_in_progress` / `attempt_unresolved`; 502 upstream error; 503 ledger capacity / `ledger_unavailable`; 500 `attempt_mark_failed` | | `GET /api/anthropic/reset-grants?accountId=...` | Read the Claude usage-limit reset grants of one Anthropic OAuth account: eligibility, each grant's resets left, validity window, and the windows it clears, plus any unconfirmed attempt still retryable | 400 no matching account; 401 re-authentication needed; 502 upstream unavailable | | `POST /api/anthropic/reset-grants/consume` | Spend one reset grant. Body `{ accountId, grantId, operationId }`; `operationId` is a UUIDv4 sent upstream as the request ID, so repeating it retries the same claim. Requires a dashboard session. A settled `reset` lifts the account's local cooldown only when it is a quota refusal recorded before the claim was first journaled and the windows the grant reported cleared cover every window that refusal named (both windows when it named none). A refusal recorded while the claim was in flight, an entitlement refusal, or an uncovered window stays, including on a same-id replay. The cached quota is dropped and usage is reread with a fresh request, so the pool can select the account before the old deadline. Model-family exclusions stay until that reread proves a family is no longer rejected. | 400 invalid body; 401 re-authentication needed; 403 `session_required`; 409 `grant_not_usable`, `in_flight`, `unresolved_prior_operation`, `unknown_outcome_expired`, `operation_identity_mismatch`; 500 `journal_write_failed`; 502 `unknown_outcome`; 503 journal busy, unavailable, or full | | `GET, PUT /api/claude-desktop` | Read or persist the Claude Desktop routed/native profile and its model visibility. PUT requires a valid `profile`, including when setting or clearing `visibility` (`visibility`: omit to keep, `null` to clear); a visibility-only body returns 400 | 400 missing/invalid profile, invalid or unavailable assignment, invalid visibility, or a visibility that hides every available model; 409 profile or supplied visibility changed during discovery/save | | `POST /api/claude-desktop/apply` | Write the saved profile to Claude Desktop's managed config | 400/500 write failure | | `GET /api/codex/desktop-compatibility/authorization` | Return HTTP 200 with `{ ok: true, supported, authorized, rememberedSession }`; absent Desktop scope is reported as `authorized: false` | Common management-boundary errors only; missing Desktop scope is not a route-specific 403 | | `POST /api/codex/desktop-compatibility/authorization` | Consume `{ grant }` from `ocx gui pair --desktop` for the existing standalone local session, for at most five minutes; return HTTP 200 with `{ ok: true, authorized: true }` | 400 `invalid_json` or `invalid_request`; 403 `desktop_authorization_required` for a refused exchange, including ordinary/remote pairing codes and remembered dashboard sessions | | `GET, POST /api/codex/desktop-compatibility/certificate` | Inspect or explicitly prepare Windows compatibility certificate trust | 403 `desktop_authorization_required` for POST; 409 stale, busy, or incomplete state | | `GET, POST /api/codex/desktop-compatibility/runtime` | Inspect or explicitly start, stop, launch, or run a bounded native compatibility trial | 403 `desktop_authorization_required` for POST; 409 unsupported build, untrusted certificate, or incomplete state | | `GET, POST /api/codex/desktop-compatibility/settings` | Read or save the next-start observation preference with its current revision | 403 `desktop_authorization_required` for POST; 409 stale, invalid, or unconfirmed configuration | | `GET /api/claude-desktop/status` | Inspect saved-versus-applied profile, Desktop health, and `appliedModels: { name: string; label: string }[] \| null`. This is the selected profile's on-disk static list, not a verified observation of the running Desktop process; `null` means no applied gateway profile or no readable static list (including discovery-only mode), not an empty list | 400 status read failure | | `GET, PUT /api/claude-code` | Read or update Claude Code gateway, auth-mode, model-map, context, agent, and sidecar settings | 400 invalid field or shape | `tokenId`, when supplied, must be a non-empty string; invalid values return `400 invalid_token_id` before credentials are read or the ledger is opened. Within the 30-day retention window, a same-`operationId` retry that omits `accountId` uses the recorded account, even if the active account changed. An executable `open` retry that omits `tokenId` uses its recorded token. An explicit different account or token is still refused. A definitive failure clears a matching speculative pending hold in the dashboard, allowing a new explicitly confirmed attempt; actual unknown outcomes remain held. An attempt is durably claimed before redemption. Only a confirmed upstream redemption response can record `redeemed`; a coupon missing from the remaining list does not prove this operation succeeded. After a timeout or missing settlement, retries inspect availability without redeeming again and return `attempt_unresolved`; a recent attempt returns `attempt_in_progress`. A late inspection refusal settles only an operation still `open`. In the same transaction, an identity-matching definitive terminal winner is replayed with HTTP 200 and its original code; an unresolved or identity-mismatched winner returns `operation_state_changed`, preserving same-ID recovery guidance. An unreadable or locked ledger returns `ledger_unavailable` without dispatching a redemption. Once a caller supplies an `operationId`, every response that cannot prove the operation is settled carries that `operationId` at the top level and keeps the caller on it: `attempt_unresolved`, `attempt_in_progress`, `attempt_reconcile_failed`, `operation_state_changed`, `operation_token_mismatch`, `attempt_mark_failed`, `ledger_unavailable`, and ledger `capacity` (the full ledger cannot reserve the ID, so an earlier request holding it may still open it later). This includes refusals before the ledger opens: a malformed `tokenId`, an unknown account, or a failed account lookup under a supplied ID return 409 `attempt_in_progress` with the ID, because another request may already hold that operation. A definitive authentication refusal is recorded atomically as a `failed` operation bound to the requested coupon, so a retry replays it; an existing operation for a different coupon is never replayed. A failed remaining-reset list settles an unclaimed operation as `fetch_resets_failed`. A redemption reply counts as confirmed only when its gRPC-Web framing is complete and every `grpc-status` it carries is the same valid value; conflicting statuses or bytes after the trailer return 502 `attempt_unresolved` and leave the operation `attempted`. An unconfirmed redemption returns HTTP 502 with `error.code: "attempt_unresolved"` and the effective `operationId`. Preserve that ID; a replacement ID would start a different operation. The CLI creates the ID before sending and prints `--operation-id` guidance if delivery or the response is uncertain. Legacy version-one `open` records and unconfirmed `redeem_failed` records are quarantined as uncertain; they never authorize another redemption. The dashboard at **Providers > xAI Grok > Accounts** lists remaining coupons and their validity windows from each account’s ticket badge. It sends a client-minted `operationId`. After uncertain delivery or an unknown-outcome response, the dashboard retains that attempt for the browser tab session, including across dialog close/reopen, page navigation, and reload. The hold is written before the request is sent and cleared only by a definitive response for the same `operationId`. Availability refreshes issue GET only and never authorize another consume POST. `ocx account grok-reset-coupons` is the terminal equivalent. Claude usage resets work the same way from **Providers > Anthropic > Accounts**. Each signed-in account row carries a ticket badge with its remaining resets, and the dialog spends one after a second confirmation. Grants differ in expiry and in the limits they clear, so the dialog lists them as choices: it preselects the usable grant that expires first, shows grants that cannot be used now as disabled with the reason, and the confirmation names the chosen grant, its expiry, and the limits it clears before that `grantId` is sent. The server checks the chosen grant again and refuses one that is not usable with `409 grant_not_usable`. A reset refills the limits its grant clears (usually the 5-hour and weekly limits) without moving the weekly reset day. When a claim does not answer, the dialog keeps its `operationId` and offers a retry with that same ID for ten minutes, which is how the Claude Code client itself recovers; a new operation on that account, for any grant, is refused until then. Spending is dashboard-only: the admin token alone gets `403 session_required`. For the concepts behind the model roster and encrypted worker-task behavior, see [Sub-agent Surface](/guides/sub-agent-surface/). ### Client integration rollback journal | Method and path | Purpose | Notable errors | | --- | --- | --- | | `GET /api/client-integrations/journal?client=...` | List rollback operations, optionally for one client. Each row includes the server-computed `deletable` flag. | 400 invalid client | | `DELETE /api/client-integrations/journal?opId=...` | Retire one older rollback operation and remove its snapshot when possible. Success returns `snapshotRemoved`; `false` means cleanup was retained for maintenance retry. | 400 missing `opId`; 404 missing or already retired operation; 409 newest operation for that client | Deletion appends a tombstone instead of rewriting the journal. The newest operation for each client is protected server-side so the current undo point remains available. For Aside, protection is per profile, and journal rows include `profileId`. ### Aside profile controls Use these dedicated paths with a compatible running proxy. `{profileId}` is a registered nonnegative integer account ID returned by the profile list; it is not a browser path. | Method and path | Purpose | Notable errors | | --- | --- | --- | | `GET /api/client-integrations/aside/profiles` | List `profiles[]`, desired `enabledCount`/`allEnabled`, actual `appliedCount`, and `total` | HTTP 200 may contain an empty, unsafe aggregate with an `error` when discovery is unavailable | | `PUT /api/client-integrations/aside/profiles` | Set every registered profile's desired state and apply it; body `{ "enabled": true }`, with optional `overwriteConflict` when enabling | 400 invalid body; 409 operation busy; 500 preference-save failure; 207 per-profile refusals | | `GET /api/client-integrations/aside/profiles/{profileId}` | Read one profile's desired `enabled` and actual integration status | 400 invalid ID; 404 unregistered profile | | `PUT /api/client-integrations/aside/profiles/{profileId}` | Change one profile with the same body as bulk PUT, leaving sibling preferences unchanged | 400 invalid body/ID; 404 unknown profile; 409 busy or refusal; 500 save/write failure | | `GET /api/client-integrations/aside/profiles/journal` | List history across registered Aside profiles | Rows include `profileId`, snapshot availability, `undoable`, and `deletable` | | `GET /api/client-integrations/aside/profiles/{profileId}/journal` | List one profile's history, including matching legacy operations | 400 invalid ID; 404 unknown profile | | `DELETE /api/client-integrations/aside/profiles/journal?opId=...` | Retire an older operation, resolving its profile from history | 400 missing ID; 404 missing operation; 409 newest operation for its profile | | `DELETE /api/client-integrations/aside/profiles/{profileId}/journal?opId=...` | Retire an older operation belonging to the selected profile | Same deletion errors; an operation cannot target a different profile | | `POST /api/client-integrations/aside/profiles/{profileId}/restore` | Undo an operation using `{ "opId": "..." }`; optional `confirmDrift: true` permits replacing later edits | 404 missing operation/profile; 409 busy, mismatch, or required drift confirmation; 410 expired snapshot; 500 save/write failure | | `POST /api/client-integrations/aside/sync` | Refresh enabled profiles through the server's mutation owner; body `{}` | 400 nonempty body/profile selector; 409 busy; 207 per-profile refusals | ## Previewing an integration change A preview reports what a change would do without doing it. These routes write nothing: no snapshot, no ownership record, no journal row, no lock, and no maintenance or recovery. | Route | Purpose | Notable responses | | --- | --- | --- | | `POST /api/client-integrations/preview` | Plan `apply`, `overwrite` or `disable` for one client; body `{ "clientId": "...", "operation": "..." }` | 400 invalid client or operation; 400 `invalid_aside_profile_path`; 409 `integration_preview_unavailable` | | `POST /api/client-integrations/restore/preview` | Plan an undo; body `{ "opId": "...", "confirmDrift": false }` | 404 unknown operation; 400 `invalid_aside_profile_path`; 409 `integration_preview_unavailable` | | `POST /api/client-integrations/aside/profiles/{profileId}/preview` | Plan one Aside profile's change, including `restore` with an `opId` | 400 invalid body or unscoped request; 404 unknown profile or operation, 409 `integration_preview_unavailable` | A plan carries `version`, `clientId`, `operation`, `state`, `foreignEdit`, a `changes` list of `kind` and `path` pairs, an opaque `fingerprint`, `canApply`, `willChange`, and an optional `refusalReason` and `profileId`. Paths are managed schema paths or the fixed `$snapshot`, `$ownership` and `$journal` markers; a position chosen at runtime appears as `*`. No configuration value, file location or selected member identity is returned. `canApply: true` with `willChange: false` means the operation succeeds and changes nothing in the managed client document, such as applying what is already applied. An Aside profile change still saves one thing in that case. Confirming it records the desired sync preference for that profile before any client document is touched, so disabling a profile whose managed block is already absent stores the preference and leaves the document and its history untouched. `integration_preview_unavailable` means no usable model roster is currently retained. A freshly started proxy is one way to be in that state; a roster retired because the configuration or the provider cache moved is another. Reading `GET /api/client-integrations` establishes one when discovery succeeds and the configuration can be identified, so it is the usual remedy rather than a guarantee. ## Confirming a previewed change Mutation routes accept `operation` and `planFingerprint` alongside their existing body. Send both or neither: a request carrying one is rejected, as is one whose `operation` disagrees with the change being requested. Aside bindings apply to a single profile, because one fingerprint cannot describe several independently changing files. The server re-plans before writing anything and returns `409 integration_preview_stale` with a freshly computed `plan` when the confirmation no longer describes what would happen. Decide again against the new plan; the request is not retried automatically. A fingerprint is an optimistic check, never authorization. Management authentication and every ownership rule still decide whether a change may happen at all. Bulk PUT returns `{ ok, clientId, changed, state, message, results }`; each result identifies its `profileId` and reports the writer outcome. Sync returns `{ ok, clientId, results }`, with per-profile refresh outcomes. Both return HTTP 200 when all returned attempts succeed and HTTP 207 with `ok: false` when any attempt refuses. HTTP 207 is a partial-result envelope, including when every attempted profile refuses: inspect each result rather than treating a 2xx response as complete success. A successful no-op can have `changed: false`; sync does not attempt disabled profiles. Single-profile writes and restores return HTTP 200 on success or the corresponding error status on refusal. Explicit changes save desired preferences before writing files. A preference-save failure leaves profile files unchanged. A later file refusal preserves saved intent and successful sibling writes; inspect the affected profile before retrying. Refusals may include `snapshotPath` and `residual: true` when recovery did not finish. Restore also reconciles the target profile's desired state, so the next sync does not reverse Undo. Deletion returns `snapshotRemoved`; `false` means snapshot cleanup still needs maintenance. The legacy `GET, PUT /api/client-integrations/aside` aliases remain available. New clients should use the dedicated paths above so an older proxy cannot ignore a profile selector. See [Aside profile controls](/guides/integrations/#aside-profile-controls) for CLI commands and the proxy upgrade, restart, and retry sequence. ### Remote Workspace Requires Hub mode and `OCX_REMOTE_WORKSPACE_ENABLED=1` on the Hub process. Disabled status is readable; mutations refuse without initializing workspace services. | Method and path | Purpose | Notable errors | | --- | --- | --- | | `GET /api/remote-workspace` | Read paired computers, current capabilities, Hub runtimes, and session snapshots | Disabled status when Hub role or explicit opt-in is absent | | `POST /api/remote-workspace/pairing` | Create a ten-minute one-use Executor enrollment code | Operator-paired GUI session only; 429 pairing capacity | | `GET /api/remote-workspace/runtimes` | Read Codex, Claude Code, and Pi availability on the Hub | — | | `GET, POST /api/remote-workspace/sessions` | List sessions or start one bound to a device, root, runtime, and access mode | POST requires an operator-paired GUI session; 409 offline/unavailable/invalid target | | `POST /api/remote-workspace/sessions/{id}/prompt` | Continue the bound model session | Operator-paired GUI session only; 409 active turn, offline Executor, or resume failure | | `DELETE /api/remote-workspace/sessions/{id}` | Stop the model runtime and encrypted Executor session | Operator-paired GUI session only; 404 unknown session | | `DELETE /api/remote-workspace/devices/{id}` | Revoke one computer and stop its sessions | Operator-paired GUI session only; 404 unknown device | Executor enrollment exchanges a one-use code at `POST /remote-workspace/pair` and then opens `/remote-workspace/agent` as a bearer-authenticated outbound WebSocket. Those two machine endpoints are not general management API authority. The bearer is device-scoped, and each work session adds a signed E2EE handshake. Ten failed pairing codes from one kernel-observed peer return `429` with `Retry-After` for the remainder of the fixed ten-minute window. Tailscale Serve clients share the management listener's loopback peer bucket; the identity header is not used for throttling because a direct local process could forge it. See [Remote Workspace](/guides/remote-workspace/) for the end-user flow and trust boundaries. Session snapshots include `resumable`. It becomes true only after the selected coding-agent runtime has durable history; notably, a new Claude Code session remains false until its first prompt completes. ### Combos | Method and path | Purpose | Notable errors | | --- | --- | --- | | `GET /api/combos` | List normalized combos and their public model ids | Catalog work can return `catalog_busy` | | `PUT /api/combos` | Create, replace, or rename one combo | 400 invalid id, target, config, rename, or ordinary collision (a combo validation 400 also names the first invalid top-level field in `field`, for example `targets` or `decisionProvider`); 409 Codex-account namespace collision | | `DELETE /api/combos?id=...` | Delete one combo and clear its selection/cooldown state | 400 missing id; 404 unknown combo | See [Combos](/guides/combos/) for target strategies, cooldowns, aliases, and routing failures. ### Codex prompt layers | Method and path | Purpose | Notable errors | | --- | --- | --- | | `GET /api/codex-prompt` | Read the prompt-layer snapshot: layers, base variants, selection, and drift state | — | | `GET /api/codex-prompt/text` | Probe the model-visible prompt text via `codex debug prompt-input`; one caller budget includes metadata, shared wait and execution; synchronous metadata is checked for expiry after it returns | Fail-soft: an unavailable probe degrades to a status in the body, not an HTTP error; timeout preserves locally read base instructions; earlier external cancellation stays cancelled | | `PUT /api/codex-prompt/toggle` | Enable or disable one toggleable layer | 400 invalid body or unknown layer; 409 `stale_revision`, `layer_not_toggleable` | | `PUT /api/codex-prompt/custom` | Replace the custom-layer set | 400 invalid body, `invalid_characters`, `body_too_large` when a normalized UTF-8 layer exceeds 65,536 bytes, `composed_too_large` over 131,072 bytes; 409 `stale_revision` | | `PUT /api/codex-prompt/base/select` | Select the default base prompt or one stored variant | 400 invalid body, `unknown_layer` for an id matching no stored variant; 409 `stale_revision`, `developer_instructions_not_owned` when the current base is external | | `PUT /api/codex-prompt/base` | Create (`id` omitted or `id: null`), edit, or delete (`delete: true`) one base variant. A supplied `id` is edit-only and must reference a stored variant. `body` is normalized (tabs expanded, CR/CRLF folded to LF) before it is measured or stored | 400 invalid body, `unknown_layer` for the `default` id or an id that matches no stored variant, `body_too_large` when the normalized UTF-8 body exceeds 65,536 bytes; 409 `stale_revision` | | `POST /api/codex-prompt/adopt` | Import `developer_instructions` from `config.toml` as a custom layer | 400 invalid body, `invalid_characters`, `body_too_large`, `composed_too_large`; 409 `config_unreadable`, `nothing_to_adopt`, `adopt_unsupported_form`, `stale_revision` | | `POST /api/codex-prompt/repair` | Repair drift between `config.toml` and the owned projection | 400 invalid body; 409 `config_unreadable`, `nothing_to_repair`, `repair_unsupported`, `stale_revision` | See [Codex prompt layers](/guides/codex-prompt/) for the layer model and the keys each layer writes. ### Configuration, startup, sync, and updates | Method and path | Purpose | Notable errors | | --- | --- | --- | | `GET /api/config` | Return the redacted, management-safe configuration DTO | — | | `PUT /api/config` | Disabled full-config replacement guard | 405; use focused endpoints instead | | `GET, PUT /api/settings` | Read runtime/startup settings or update auto-start, stream mode, app-owned memory budget, and `codexAccountPickerEnabled` | 400 invalid, non-object, or empty update | | `GET, PUT /api/native-reasoning-retention` | Read resolved model/account reasoning-retention booleans; partial PUT preserves omitted fields, JSON `null` restores defaults. See [native reasoning retention](/reference/configuration/server/#native-reasoning-retention). | 400 unknown field, invalid type or non-object/non-null body | | `GET, PUT /api/workflow-budget/settings` | Read the effective per-task workflow ceilings with defaults and allowed ranges; partial PUT preserves omitted fields, JSON `null` restores defaults. See [workflow limits](/reference/configuration/server/#workflow-limits). | 400 unknown field, non-integer or out-of-range value, or non-object/non-null body | | `GET /api/startup-health` | Read cached service/shim startup health | — | | `POST /api/startup-action` | Install or repair the service or Codex shim | 400 invalid action; 500 action failure | | `GET, POST /api/windows-tray` | Read Windows tray state or install/start/stop/uninstall it | 400 unsupported platform/action; 500 operation failure | | `GET /api/diagnostics/project-config` | Read cached project configuration warnings | — | | `POST /api/sync` | Sync the current model catalog into Codex | 500 failed sync | | `GET /api/update/check` | Asynchronously check the `latest` or `preview` package channel and refresh the package cache on success | 400 invalid tag | | `POST /api/update/run` | Asynchronously check a fresh package version, then start an update job, optionally followed by restart | 400 invalid body; 409 `update_restart_unsupervised` when the proxy runs inside a systemd unit other than OpenCodex's own user service, or the worker cannot leave the service cgroup (with or without restart, since the update stops the proxy first); job-specific conflict/error status | | `GET /api/update/status` | Poll an update job by id | 404 unknown job | | `GET, PUT /api/sidecar-settings` | Read or update web-search and vision sidecar model/backend settings | 400 invalid shape, backend, or limit | | `GET, PUT /api/shadow-call-settings` | Read or update shadow-call interception settings, including `sourceModels`; GET also returns the runtime-owned `sourceModelOptions` inventory | 400 invalid shape or value, including an empty, duplicate, whitespace-bearing, or provider-qualified source prefix, or more than 32 prefixes / 128 characters per prefix; source-list failures carry `code: shadow_call_source_invalid`, target conflicts `code: shadow_call_target_invalid` | ### Logs, usage, and storage Request logs retain `servedModel` when the upstream identifies the model that answered, and `wireModel` when the model sent upstream differs from the client-facing model. The dashboard shows `wire → served` when those identities differ; its tooltip preserves both values. Missing upstream model evidence remains absent rather than being inferred from the requested model. Failed request rows can include bounded `upstreamErrorType`, `upstreamErrorCode`, and `upstreamRequestId` diagnostics. On the Codex upstream WebSocket path, a bare error followed by EOF retains recognized rate-limit, overload, or client-refusal codes in the synthesized failed terminal. Request logs record these as 429 for `rate_limit_exceeded` / `rate_limit_error`, 503 for `server_is_overloaded` / `overloaded_error`, and 400/401/403/404 for `invalid_request_error` / `authentication_error` / `permission_error` / `not_found_error`. A recognized type without a code uses the same status. On the streaming path, an explicit unknown code records the 5xx status the Codex WebSocket wrapper states as a top-level integer `status` or `status_code` (one of the two, not both); otherwise, and for buffered JSON callers, it remains a generic 502 failure. The client terminal keeps `upstream_server_error` for unknown codes either way. Bare-error status is provisional: a genuine completed, failed, or incomplete terminal replaces it before account-health recording. Refusal precedence is unchanged. This diagnostic mapping adds no automatic replay or retry. `GET /api/logs` accepts an optional opaque `cursor` from its previous response. The envelope preserves `logs`, `total`, `generatedAt` and `timeZone`, and adds `cursor` and `reset`. Without a cursor it returns the full filtered window. A valid unchanged prefix returns only appended rows; `reset: true` replaces the client window after edits, eviction, query changes or restart. Invalid cursors return HTTP 400 with `error.code: "invalid_cursor"`. Authentication is unchanged. The dashboard falls back to full snapshots for older servers. This reduces response bytes for stable windows; server projection remains bounded by the current window size. Successful `/api/logs` `displayMetrics.decodeTokPerSecond` values carry `timingBasis: "generation-window" | "legacy-post-visible-output"` alongside `kind`, `value` and `estimated: true`; attempt values identify their own window. Unavailable results keep their existing `reason` and no timing basis. The field is derived only at read time: stored JSONL, end-to-end `tokPerSecond`, request-history DTOs and aggregate throughput are unchanged. Older DTOs can omit the field; clients must treat the timing basis as unknown in that case. The dashboard names these methods **Generation window** and **After visible output**, with **Timing unknown** for a missing or unfamiliar basis. Request details show **Output rate during generation (est.)**, **Output rate after first visible output (est.)**, or **Output rate (est.; timing method unknown)** and a visible explanation of the timing method when a rate is available. | Method and path | Purpose | Notable errors | | --- | --- | --- | | `GET /api/logs` | Query filtered in-memory request logs | — | | `GET, PUT /api/debug` | Read debug flags; set, clear, or reset capture categories | 400 invalid or empty update | | `GET /api/debug/logs` | Read bounded provider/debug log entries | — | | `GET /api/debug/usage-logs` | Read bounded usage-debug entries | — | | `GET /api/debug/injection-logs` | Read bounded guidance-injection debug entries | — | | `GET /api/claude/inbound-debug` | Read Claude inbound debug state and entries | — | | `GET /api/usage` | Scan the usage ledger into compact aggregates of readable rows, then incrementally fold verified appends; summarize by preset or inclusive custom window and client surface, with a Codex `accounts` breakdown keyed by stable non-PII log labels | 400 invalid custom bounds; 500 `{ "error": "read_failed" }` if storage cannot be read | | `GET /api/usage/devices` | List current Remote Link key IDs and aliases for an authorized dashboard session | 403 without the required dashboard session; 503 if the link store cannot be read | | `GET /api/usage/source-facets` | Count recent app and device choices for an authorized dashboard session | 400 for invalid filters; 403 without the required session; 503 if the scan or inventory is unavailable | | `GET /api/usage?jev=1` | Project persisted JEV decisions and their physical target sends. Optional `comboId` selects one Combo; `range` accepts `7d`, `30d`, or `all` (default `30d`). | 400 invalid `comboId`; 500 `{ "error": "read_failed" }` if the ledger cannot be read | | `GET /api/usage/timeline` | Bucketed usage by model/account; accepts `hours`, `bucketMinutes`, `metric`, `aggregation`, `grouping`, comma-separated `models` and repeated `hiddenProvider` filters | 400 invalid query or limits | | `GET /api/metrics` | Return process-local Prometheus text metrics for requests and cached Kiro quota. Kiro accounts use bounded opaque digest labels; raw account and credential identifiers are never exported. | 404 when `metricsExport.enabled` was not true at startup; ordinary management authentication is required and data-plane credentials grant no access | | `GET /api/storage` | Scan Codex storage usage by bucket | Returns an `error: "scan_failed"` payload on scan failure | | `POST /api/storage/cleanup/preview` | Preview archived-session cleanup and return a binding digest | 400 `invalid_json` or `invalid_percent` | | `POST /api/storage/cleanup` | Quarantine or permanently remove the previewed archived set | 400 invalid input; 409 stale/busy/referenced state; 500 filesystem/database failure | | `GET /api/storage/trash` | List quarantined cleanup entries | 500 `trash_list_failed` | | `POST /api/storage/trash/restore` | Restore one quarantined entry | 400 invalid id; 404 missing trash; 409 busy/destination conflict; 500 restore failure | | `GET /api/storage/trash/restore/test-stream` | Test-only restore stream hook | 404 `not_available` when test hooks are off | | `GET, PUT /api/storage/cleanup-policy` | Read or update scheduled cleanup policy and job state | 400 invalid policy | | `POST /api/storage/cleanup-policy/run` | Start a manual cleanup-policy run | 409 `already_running`; 500 `cleanup_failed` | | `GET /api/storage/cleanup-policy/test-stream` | Test-only policy stream hook | 404 `not_found` when unavailable | Timeline model identifiers split at the first slash, so nested native ids such as `github-models/openai/gpt-4.1` are supported. Provider exclusions apply before excess series are folded into `other`; the additive `appliedFilters` object echoes the normalized model/provider filters. The final bucket includes the current partial interval. Companion settings are not applied implicitly to general API calls. `GET /api/metrics` returns `Content-Type: text/plain;version=0.0.4`. Counters and histograms reset when the process restarts; `opencodex_metrics_process_start_time_seconds` identifies that boundary. Histogram buckets are cumulative and end with `le="+Inf"`, equal to the family count. | Metric family | Labels | Meaning | | --- | --- | --- | | `opencodex_logical_requests_total` | `protocol`, `result` | One observation per finalized logical request. | | `opencodex_physical_sends_total` | `protocol` | Actual upstream sends summed from finalized attempts. | | `opencodex_recoveries_total` | `protocol`, `recovery` | Distinct recovery kinds observed per attempt, projected to a closed class. | | `opencodex_request_failures_total` | `protocol`, `cause` | Finalized requests that did not deliver an answer, by the cause the recorder derived. Counter only; no histogram carries a cause. | | `opencodex_request_duration_seconds` | `protocol`, `result` | Fixed-bucket duration histogram for finalized requests. | | `opencodex_ttft_seconds` | `protocol`, `result` | Fixed-bucket TTFT histogram for requests with observed first output. | | `opencodex_ttft_missing_total` | `protocol`, `result` | Complementary count for requests without observed TTFT. | | `opencodex_metrics_process_start_time_seconds` | none | Process-local reset boundary. | | `opencodex_kiro_quota_{used_credits,limit_credits,used_percent,seconds_to_reset}` | `account` (opaque `o` plus six hex digits; at most 32 distinct live accounts) | Identity-matched cached Kiro plan readings. Missing, stale, future-dated, or reset-passed readings emit no sample; scraping never probes upstream. | The `recovery` label takes one of a fixed set of classes: `transient`, `connection`, `credential`, `rate_limit`, `quota`, `policy`, `ciphertext`, `payload`, `empty_completion`, `effort_downgrade`, `fast_downgrade` and `other`. The recovery set is closed; Kiro quota gauges use only the opaque account digest label described above, never a raw account identifier. `fast_downgrade` records an Anthropic Fast refusal repaired at standard speed; it is distinct from the reasoning-effort `effort_downgrade` class. `rate_limit`, `quota`, `policy` and `ciphertext` are separate because the operator response differs: wait out the limit, move to another account, change the prompt, or drop stale encrypted state. A rejected opaque reasoning blob counts as `ciphertext` rather than `payload`. If a scanned row exceeds the existing parser size limit, `GET /api/usage` and `GET /api/keys` keep the readable-row aggregates and add `usageIncomplete: true` with `usageIncompleteReason: "oversized_rows"` at response level. This diagnostic survives cached responses and incremental appends, including empty or unmatched results; a rebuild recalculates it. No provider, model, or API-key identifier is shortened to make a row fit. An absent flag is not proof that every ledger record was valid. This is separate from `historyTruncated`, `entriesTruncated`, and token measurement coverage. The JEV projection reports decision counts and gates, applied versus fail-open picks, decision latency/confidence, TypeSafe-reported decision tokens, physical target send counts, available model token/cache totals, reasoning-effort picks, and requests that sent to a target other than JEV's initial choice. `attempts` are summed from each persisted attempt's `sendCount`; a zero-send row is not a fallback. One reported usage object is counted once even when its attempt retried, so the measured-attempt count can be lower than the physical-send count. Model cardinality is bounded; an explicit overflow row aggregates additional identities without dropping summary totals. JEV stats use the same append-only `usage.jsonl` ledger and cooperative scanner as ordinary usage. Cold reads scan the current ledger, unchanged polls perform no file read, and verified growth folds only the appended suffix. Concurrent identical requests share one scan. The persisted JEV record is closed and content-free: Combo id, selected provider/model/effort, decision gate, latency, optional confidence/probability, and optional numeric decision usage. It never stores prompts, headers, credentials, tool arguments, or raw TypeSafe responses. Oversized rows retain the same positive `usageIncomplete` diagnostic as the ordinary usage endpoint. New xAI attempts in `usage.jsonl` include a request-time `credentialSource`: `grok-oauth` for the resolved Grok CLI OAuth transport, or `xai-api-key` for the public xAI API key transport. This fixed label contains no credential or account identifier. It belongs to each item in `attempts`, so a combo's aggregate token total must not be attributed to its final provider. Custom destinations and historic rows omit the field; consumers must not infer subscription usage from the current configuration, model name, or inbound API key. The log reports usage, not subscription invoice amounts. API-key attempts also record `accountLogLabel` as `k` followed by 32 lowercase hex digits. The label is the first 128 bits of SHA-256 over `JSON.stringify(["ocx-key-account-v1", providerName, entryId ?? null, reference])`. The reference is the configured key value captured for the physical request, before environment or keychain resolution. Raw keys, references, and pool IDs are not written to the label field. A consumer can derive the same label from its local configuration without resolving secrets. Changing a literal key or reference changes the label; replacing the secret behind an unchanged reference keeps the same logical account. Older unlabeled records cannot be attributed reliably. Anthropic OAuth pool attempts and rows also record `accountTag`, the `p` plus six lowercase hex digits already shown in the logged provider (`anthropic-p2e22d0` has the tag `p2e22d0`). It names the pool account that served each attempt, so a failover attempt carries the replacement account's tag. It contains no email, account ID, or credential, and it does not change `accountLogLabel` or the per-account usage summaries. A provider without that suffix, such as a pool-off translated request, has no tag. Older rows and malformed values omit the field. Key selection is recorded after queued requests have been rebuilt for the current selection. When a retry changes keys, `attempts` retains a separate record for the preceding key, including reported usage from failed responses. Missing usage remains unreported. Routed adapter terminals are observed before image/search loops or continuation guards combine their usage. Consumers sum the flat attempts by provider/account and do not add the parent combo total again. These records identify usage; provider quota percentages remain separate upstream observations. For app and device attribution, `GET /api/usage` accepts both `client` and `device` together. `client` is `all`, `codex`, `claude_code`, `claude_desktop`, `grok`, `opencode`, `aside`, `other`, or `unknown`. `device` is `all`, `no-key`, `key`, or `unconfigured`; `key` requires exactly one case-sensitive `apiKeyId`. These filters require `surface=all` or an omitted surface and cannot be combined with the JEV or failure projections. Invalid or repeated source options return 400. The response echoes the applied `sourceFilter` and `legacyUnclassifiedRequests` so consumers can verify the filter was applied. Earlier records with no app field remain explicitly unclassified; the Codex selection includes legacy Codex-surface records in that count without assigning them a specific app. `no-key` includes requests without a configured key, including older and environment-admitted records; it does not prove a request came from a particular physical device. `unconfigured` requires a dashboard session and selects configured-admission rows whose key ID is absent from the current configured-key list. It describes current configuration, not proof that a key was deleted or which device used it; older rows without admission metadata are not included. The dashboard-session-only `/api/usage/source-facets` accepts the same `client` and `device` parameters and provides counts for a captured 30-day window, the filter echo and incomplete-read status. App counts respect the chosen device; device counts respect the chosen app. Individual key counts are limited to configured keys. Its `legacyUnclassifiedRequests` is the unclassified subset of the Codex option for the chosen device, regardless of the selected app. This endpoint and `unconfigured` reports use `no-store`. Configured IDs that cannot be selected exactly, such as IDs with surrounding whitespace, remain in the configured snapshot but are omitted from individual device choices and counted in `unavailableConfiguredKeys`; they are never silently trimmed or classified as unconfigured. If a dashboard session expires during an authorized facets or `unconfigured` scan, the server returns 401 instead of the 403 used for a credential that lacks the required dashboard scope. For bounded resource use they refuse snapshots with more than 1,024 configured keys, an ID over 256 characters, or more than 65,536 total ID characters rather than silently truncating them. Client labels are best-effort classifications of inbound headers, not authentication, and raw headers are not stored as client attribution. The current classifier recognizes documented Codex, Claude and OpenCode signatures; it does not yet identify Grok, Aside or other Chat API apps automatically, so their unrecognized requests remain `unknown`. The `/v1/usage` data-key endpoint accepts `client` and echoes its authenticated-key scope without exposing the key ID. A Remote Link management relay accepts new source filters only for its authenticated link key; source-filtered snapshot bounds describe matching rows, not the whole ledger. The Child requires the Home to echo the requested scope and refuses an unconfirmed response. Source-filtered HEAD requests through the Child return 405 because a bodyless response cannot confirm the scope. Existing requests without the new source dimensions retain their earlier behavior. `GET /api/usage` reads `~/.opencodex/usage.jsonl` from the beginning through the current ledger snapshot on a cold start. It processes fixed 1 MiB chunks and retains compact aggregate state rather than every normalized request row. Later refreshes validate the previous line boundary and fold only newly appended complete rows. Concurrent callers share the same refresh. Range and surface predicates are applied to the readable-row aggregate, so the former read-byte window and parsed-row cap cannot omit an earlier file prefix from 7-day, 30-day, or all-history totals. `managementUsageMaxReadBytes` remains accepted for compatibility with bounded legacy readers, but changing it no longer expands or reduces the history summarized by this endpoint. Cold ledger scans yield between records so health checks and other local requests can continue while a large usage report is calculated. A single record is processed atomically. Pass both `since` and `until` to select an inclusive custom interval. Each accepts integer Unix epoch **milliseconds**, or a full ISO datetime with an explicit timezone. Invalid dates, negative or out-of-range values, reversed bounds, and a single bound are rejected. Custom bounds override `range`; the response keeps the preset `range` field for compatibility and adds `customWindow: true`, the exact `since`, and `until`. `generatedAt` remains the time the report was produced. Custom windows filter individual ledger entries before daily aggregation, including partial first and last days. They preserve `surface`, `provider`, `model`, and `apiKeyId` filtering and never reuse or overwrite unfiltered preset summaries. The daily chart remains capped at 366 local calendar days; totals cover the full requested interval. Snapshot-window fields describe the scanned ledger before the time filter, so they can extend beyond the requested bounds. Provider, model, `apiKeyId`, source and custom-window queries are answered from a derived candidate index (`~/.opencodex/usage-filter-index.sqlite`) instead of a whole-ledger scan. The index records each complete row's byte offset with the fields those filters select on, so a new filter combination reads and normalizes only its matching rows. The first filtered query after the index is missing or invalid performs one full ingest; later queries ingest only newly appended bytes. The totals are unchanged by the index: a filtered response reports what a full scan would report. The index is disposable and rebuildable — delete the file and the next filtered query rebuilds it from `usage.jsonl`, which stays the only authority and is never truncated or rewritten. A replaced, truncated or rewritten ledger rebuilds the index rather than extending stale rows. The index is created private to your user, and a file at that path that is not this index is left alone. If the index cannot be used — an unwritable home, a full disk, another process holding it, or a damaged file — filtered usage falls back to reading `usage.jsonl` directly, which is slower but returns the same totals. A passive management read from a Remote Link Child only uses an index that is already current and never creates or modifies one. A query that selects most of the ledger (for example `client=all&device=all` with no provider, model or key) still has to read every row in its window; the index removes the repeated whole-ledger work for selective filters, not the cost of a report whose result is the whole ledger. The Usage page accepts local date/time inputs. Its selected ending minute includes the entire minute through `:59.999`. Choosing a preset or clearing the custom window restores preset behavior. This adds exact range selection and existing cost estimates; it does not add hourly chart buckets or offline reporting. The runtime ledger is append-only. Replacing or truncating it, or changing local pricing/time-zone inputs, triggers a complete rebuild. If you manually edit an older row in place while the proxy is running, restart the proxy (or replace the file) before relying on the new total; incremental refreshes verify the append boundary, not every previously aggregated byte. The response still includes `historyTruncated`, `truncatedPrefixBytes`, `entriesTruncated`, and `entriesDropped` so older clients can consume the same wire shape. A successful whole-ledger scan reports `false`, `0`, `false`, and `0`, respectively. These are legacy compatibility fields, not a signal that the endpoint read only a configured-size tail. For `GET /api/usage?range=30d&surface=codex`, `accounts` contains one row per observed Codex pool label. Each row reports `accountLogLabel`, token totals, `usageCoverageRatio`, and an optional `estimatedCostUsd` based on the currently configured display pricing. Active user `modelCosts` overlays take priority over bundled verified catalog and price fallbacks, and historical usage is re-estimated from the pricing active when the summary is read. This is an API-equivalent estimate, not a subscription charge. New main-pool requests use the reserved `main` label; legacy bare `openai` rows remain in an ambiguous bucket instead of being reassigned from current configuration. Manual model prices can also be edited from **Models → Price**. A manual-pricing badge survives catalog reloads. Prices are stored in `providers..modelCosts` and survive catalog sync. Explicit all-zero user rates mean a known-zero estimate; **Reset to automatic** removes the override and restores the usual catalog fallback. These remain display estimates, not bills. `GET /api/providers/{provider}/model-costs` returns `{ provider, modelCosts }`, with sanitized four-rate entries and their optional `promptLengthPricing` policy, keyed by exact upstream model ID. `PUT` on the same route accepts `{ modelId, cost }`, where `cost` contains `{ input, output, cacheRead, cacheWrite }` and optionally `promptLengthPricing`, or is `null` to reset. All four rates must be finite numbers from 0 through 1,000,000, in USD per 1M tokens. Unknown fields and malformed rates are rejected. A write preserves other models' overrides and returns `{ ok: true, provider, modelId, cost }`; reset returns `cost: null`. The **Model price** dialog offers **Automatic**, **Flat rate**, and **Custom threshold** prompt-length pricing. Automatic (also the default when the policy is absent) retains catalog context rules with the saved base rates. Flat disables context adjustments. Custom selects four absolute alternative rates using one positive safe-integer `thresholdTokens` and `comparison` (`"gt"` for `>`, `"gte"` for `≥`). All prompt tokens count, including cache reads and writes; output does not. The selected rates apply to the whole request, including output, not just the excess tokens. Custom replaces the catalog context rule both below and above its threshold. Custom rates are standard-speed rates: an applicable Fast/Priority adjustment applies once after rate selection and follows the catalog's Priority relation for that model. Only a model whose catalog relation is `lower-bound` reports `priorityLowerBound: true`; a model with no catalog rule applies any Priority multiplier once. `{ "mode": "automatic" }` is accepted on write and stored as an absent policy, so GET and PUT receipts never contain it. **Reset to automatic** removes the entire override, including base rates and the policy. See the [configuration example](../configuration/providers/#prompt-length-pricing). ```bash ocx models price ollama/custom-model --json ocx models set-price ollama/custom-model --input 0.50 --output 1.50 ocx models set-price ollama/custom-model --input 0 --output 0 ocx models set-price ollama/custom-model --auto ``` Omitted CLI cache-read/cache-write rates default to zero. Use `--cache-read` and `--cache-write` to set them explicitly. A provider name remains an exact configuration identity; account display labels are not editable provider names. Rows in `models`, `providers`, and `days[].models` also carry `cacheHitRate`: the share of input tokens served from the provider's prompt cache, clamped to `[0, 1]`. It is `null` — never `0` — when the provider reported no cache telemetry or the row has no input tokens, because "no cache data" and "a genuine 0% hit rate" are different facts and a chart that renders them alike is misleading. :::caution Storage cleanup endpoints can move or permanently remove archived session data. Always preview first and submit the returned digest. Prefer quarantine when recovery may be needed. ::: Cleanup recovery manifests are published atomically, preserving the previous complete record if a replacement fails before publication. This does not reverse a permanent purge: restore can still fail when a recorded session has no surviving rollout file. ### Models and catalog | Method and path | Purpose | Notable errors | | --- | --- | --- | | `GET /api/catalog` | Return the installed Codex catalog document. Remote clients should prefer the data-plane `GET /v1/catalog`, which still requires an ordinary data-plane credential but not an admin token. | 404 catalog not found | | `GET /api/models` | Return the dashboard/CLI model rows | `catalog_busy` when gathering is saturated | | `GET /api/client-config?client=...` | Build a read-only client config for any supported file integration | 400 unsupported client; 503 catalog unavailable | | `PUT /api/disabled-models` | Replace the shared disabled-model list | 400 invalid JSON | | `PUT /api/model-visibility` | Atomically change provider- or model-level visibility | 400 invalid provider, scope, target, or body; 409 `initial_model_selection_pending` (refresh the model list and retry) | | `GET, POST /api/custom-models` | List custom models or add one | 400 invalid fields; 404 provider missing; 409 duplicate model | | `PUT, DELETE /api/custom-models/{id}` | Edit or delete one custom model | 400 invalid id/fields; 404 not found; 409 duplicate model | | `GET, PUT /api/selected-models` | Read provider allowlists and availability, or replace one allowlist | 400 missing provider/body; 404 unknown provider; PUT 409 `initial_model_selection_pending` | | `GET, PUT /api/model-presets` | Read preset summaries or choose preset/all/custom mode | 400 invalid mode or unsupported preset; 404 unknown provider; PUT 409 `initial_model_selection_pending` | | `PUT /api/model-settings` | Edit one routed model's capability axes in place | 400 missing provider/modelId, unknown or native/combo provider, malformed field, unknown field, non-exact model id, or an invalid default effort for the resulting ladder; 500 when the config could not be saved (live config left unchanged) | `PUT /api/model-settings` takes `{ provider, modelId }` plus any of `contextWindow`, `inputModalities`, `responsesCustomTools`, `reasoningEfforts`, and `defaultReasoningEffort`. It writes the provider-level per-model maps the runtime already reads (`modelContextWindows`, `modelCapabilities..inputModalities`, `modelCapabilities..responsesCustomTools`, `modelReasoningEfforts`, `modelDefaultReasoningEfforts`), so an edited row keeps its discovery provenance instead of being replaced by a custom model. `inputModalities` accepts `text`, `image`, and `audio`; `responsesCustomTools` accepts a boolean or `null` to inherit the provider setting. The dashboard has no control for it: its model settings Restore clears the context window, modalities and reasoning settings but leaves `responsesCustomTools`, so clear it with `responsesCustomTools: null` or `ocx models set --reset`, which clears every axis including this one. `reasoningEfforts` must be a subset of the efforts the runtime knows. Unknown request fields are rejected by name. `modelId` must be exact, without surrounding whitespace, control characters, excessive length, or a reserved object-property name. `contextWindow` must be `null` or a positive safe integer. When `responsesCustomTools` is `false`, native Responses compaction also lowers custom-tool history. History that cannot be lowered safely returns HTTP 400 with `invalid_request_error` before sending anything upstream. Every field is optional, and `null` **clears** the declaration rather than writing a default, which hands the fact back to the registry, the catalog, and the provider. An empty `inputModalities` array also clears, while an empty `reasoningEfforts` array is stored as an explicit "this model has no reasoning rungs" override — it does not clear. Clearing `inputModalities` also removes the exact legacy `modelInputModalities` entry for that model, so a restore cannot leave an older declaration in force; family keys shared with other models stay. An emptied per-model map is removed instead of left as `{}`. A request that changes nothing answers `changed: false` with the stored state. The receipt also reports `saved` (whether this request published config), `hasOverrides` (whether any editable axis remains stored), and `catalogRefresh` (`committed`, `skipped`, or `failed`). These fields distinguish a no-op with stored declarations from a model with nothing to restore. A changed request persists atomically; an unpublished save failure leaves the live config unchanged. After publication the server drops that provider's cached `/models` result and reports the catalog outcome. A published write followed by a bookkeeping error still returns `saved: true` with a skipped refresh. The gather bakes resolved hints into the rows it caches, and a cache hit may only lower a configured window, so a raised or cleared override would otherwise read back the previous answer for the whole TTL. Only routed providers are addressable: `openai` is the native passthrough lane and `combo` is a synthetic row, so neither is a provider whose per-model maps these facts come from. Display name is not part of this route; use `PUT /api/providers/{provider}/model-display-names`. `GET /api/models` reports the exact stored `contextWindowDeclared` separately from the effective `contextWindow`. The Models editor starts from the declaration and shows the effective window as an inherited hint when no declaration exists. If a save outcome is unknown, or the save succeeded but the model list did not reload, the dialog disables further writes and offers a read-only Reload. After a successful reload, reopen the row to inspect the stored values. A `catalogRefresh` that failed, or was skipped with `retryable: true`, leaves the save in place and shows a warning to run Sync; a non-retryable skip means no managed Codex catalog and is a clean save. A manual model replaces the Models dashboard row with the same provider and model ID. For OpenAI, the manual row keeps `openai/` and supports the same visibility controls as other routed models; removing it restores the bare native dashboard row. Explicit account-qualified native rows stay separate. This does not rename bare native routes or change account entitlements. Non-native OpenAI visibility targets must match a configured manual model. Valid PUT requests to `/api/selected-models` and `/api/model-presets` return HTTP 409 with code `initial_model_selection_pending` until a reliable initial model list is available. Refresh model discovery (for example, `GET /api/models`) and retry after it succeeds. Successful visibility/selection writes to `/api/disabled-models`, `/api/model-visibility`, `/api/selected-models`, and `/api/model-presets` report follow-up outcomes in `catalogRefresh` and `clientIntegrations` when that refresh path runs. HTTP 200 and `ok: true` confirm the selection save; they do not guarantee every client catalog updated. Inspect `clientIntegrations[]` for `ok: false`, `client`, optional Aside `profileId`, and the refusal `reason`; recovery details may also include `refusalReason`, `snapshotPath`, and `residual`. The Models page keeps the saved selection and shows a separate client-refresh warning. Inspect Integrations and resolve the reported issue before retrying `ocx sync`. Missing outcome fields from an older server do not establish successful recovery. ### OAuth accounts, provider keys, and data-plane keys OAuth account rows always include `plan`: a validated upstream subscription label or `null` when unknown. Anthropic profile tiers report labels such as `max_20x`, `max_5x`, or `pro`; Antigravity prefers the paid tier (for example `g1-pro-tier`) over the current tier. Labels are read on login/import or refresh, never inferred from quota percentages. | Method and path | Purpose | Notable errors | | --- | --- | --- | | `GET /api/oauth/providers` | List providers with public OAuth login flows | — | | `GET /api/key-providers` | List providers configured through API-key login | — | | `POST /api/oauth/login` | Start an OAuth login or account-add flow. `mode: "code"` starts a code-display login (Anthropic only) and returns `mode`, `flowId`, `expiresAt`; xAI `device: true` returns `flowId` | 400 unknown/invalid provider, invalid `mode`, `code_mode_unsupported`; 403 `antigravity_risk_not_acknowledged` for `google-antigravity` without `acknowledgeAntigravityRisk: true` (also required by `POST /api/oauth/accounts/import`); `oauth_mutation_busy` | | `POST /api/oauth/login/code` | Submit a manual callback URL or authorization code. For a code-display flow (with `flowId`) returns the token-exchange outcome `{ok, account}` / `{ok:false, error}` | 400 invalid provider/code, `state_mismatch`, `invalid_or_expired_code`, `provider_unreachable`, `oauth_authentication_failed`, `malformed_input`; 409 `no_pending_login`; `oauth_mutation_busy` | | `POST /api/oauth/login/cancel` | Cancel a public in-progress OAuth flow or dismiss its settled failure; an optional `flowId` names one flow (a flow of another provider is refused) | 400 unknown provider | | `GET /api/oauth/status` | Poll one provider's OAuth flow; for xAI, `flowId` selects the device attempt, while omitting it retains provider-wide polling. A failed flow reports a fixed public `error` and a machine-readable `errorCode` from the same vocabulary as the paste response, including `oauth_authentication_failed` for xAI denial or a refused redirect and `provider_unreachable` for an xAI server failure | 400 unknown provider | | `POST /api/oauth/logout` | Remove the selected provider credential | 400 unknown provider; `oauth_mutation_busy` | | `GET /api/oauth/accounts` | List masked accounts; Anthropic and generic OAuth account rows include their `paused` state. Kiro rows include `autoSelectable` and a closed `skipReason` when excluded from automatic selection; an active singleton may still send. Quota remains opt-in. | 400 invalid provider | | `DELETE /api/oauth/accounts` | Remove one account | 400 invalid provider/id; 404 account missing; `oauth_mutation_busy` | | `PUT /api/oauth/accounts/active` | Select the active OAuth account | 400 invalid provider/account; 404 account missing; 409 account paused; `oauth_mutation_busy`; 503 `affinity_reset_not_persisted` (Anthropic: `selectionCommitted: true`, `retryable: true`; account change saved; resend the same request even if already active) | | `PUT /api/oauth/accounts/pause` | Pause or resume one Anthropic or generic OAuth account. Body `{ provider, accountId, paused }`; pausing the active account selects the next usable account when available. Pause is durable and independent of pool enablement; resume preserves health and credentials. | 400 unsupported provider or invalid body; 404 account missing; `oauth_mutation_busy`; 503 `affinity_reset_not_persisted` (Anthropic: `pauseCommitted: true`, `retryable: true`; pause state saved; preserve the account and pause state, add `retryAffinityReset: true`, and retry to confirm the reset even after a server restart) | | `GET, PUT, PATCH /api/pool/settings` | Read or update pool policy for any kind (codex, anthropic, generic); answers with the same keys for all three and declares in `supported` which the kind honours | 400 unknown provider, a field the kind does not support, or an invalid value | | `GET, PUT, PATCH /api/oauth/accounts/pool` | Legacy per-pool policy for Anthropic and generic OAuth providers; superseded by `/api/pool/settings` and kept for existing clients | 400 codex or api-key provider, or invalid policy | | `POST /api/oauth/accounts/clear-cooldown` | Clear one OAuth account's runtime cooldown | 400 invalid provider/account | | `PUT /api/oauth/accounts/alias` | Set or clear an OAuth account alias | 400 invalid provider/account/alias | | `GET, POST, DELETE /api/providers/keys` | List masked provider keys, add/activate one, or remove one | 400 invalid input; 404 provider/key missing | | `PUT /api/providers/keys/active` | Select a provider's active key | 400 invalid input; 404 provider/key missing | | `PUT /api/providers/keys/alias` | Set or clear a provider-key alias | 400 invalid input; 404 provider/key missing | | `PUT /api/providers/keys/pause` | Pause or resume one provider API key. Body `{ name, id, paused }`; pausing the active key selects the next usable key in ring order. Success includes the resulting `activeAccountId` (or `null`) and `activeAccountChanged`. | 400 invalid input; 404 provider/key missing | | `GET, POST, PATCH, DELETE /api/keys` | List, create, edit, or delete data-plane admission keys | 400 invalid body/id; 404 key missing | | `PUT /api/oauth/accounts/affinity-reset` | Confirm a provider-wide session-affinity reset without requiring an account. Body `{ provider }`; success includes `affinityResetConfirmed: true`. CLI: `ocx account reset-affinity anthropic --json` (`anthropic2` supported). | 400 invalid body/provider; 503 `affinity_reset_not_persisted`, `retryable: true` | The dashboard retains an unconfirmed affinity-reset warning even when the saved account disappears. Loading errors and paused or reauthentication-blocked active targets keep their retry with feedback. Once a loaded list confirms absence, Retry uses `PUT /api/oauth/accounts/affinity-reset` with `{ provider }`; it clears the warning only after `affinityResetConfirmed: true`. This provider-wide operation clears all bindings, including those created since the first failure, without selecting or resuming an account, and also works with an empty roster. Deleting an account with an outstanding reset sends `retryAffinityReset=true`; a failed publication returns 503 `affinity_reset_not_persisted`, `deletionCommitted: true` and `retryable: true`. The account is already deleted: retry the reset-only endpoint, not deletion. Plain deletion preserves surviving-account affinity. Reset-only cleanup is limited to the registered Anthropic OAuth instances and retains the ordinary management authentication/origin checks. `POST /api/oauth/login/cancel` can also dismiss the selected settled failed login attempt. It leaves stored credentials and successful login results intact; status then reports the remaining flow or idle. Cancelling an in-progress attempt still records its cancelled outcome. For xAI, an unknown, successfully completed or other-provider `flowId` returns `{ok:true,cancelled:false}` without affecting another attempt; a non-string or over-128-character ID returns 404. Omitting it targets the latest attempt. For Anthropic, `routes` is an ordered array of `{name, match, accounts, fallback?}` rules on both settings endpoints. GET and write echoes include `routes` (`null` when absent); unified DTOs expose `routes: null` for other kinds. A supplied `routes` on another kind is rejected. Omission preserves rules, `[]` matches nothing, and `null` clears them. The `accounts` values are stored IDs; removed IDs remain valid in a rule so re-adding an account can restore routing. Management responses retain valid configured names; request logs identify a match only as `route:#` (1-based list position). If a hand-edited stored rule is invalid, both settings GETs return `routes: null` and a `routesError` diagnostic instead of presenting that rule as valid; the stored value remains available for correction. Valid or absent rules omit `routesError`. Credential list responses are deliberately masked. OAuth access tokens and complete provider API keys are not returned to dashboard clients. ### Protocol paths | Method and path | Purpose | Notable errors | | --- | --- | --- | | `GET /api/protocols` | Return the protocol contract version, which APIs are served, the protocol settings, the current policy revision, and the request features a preview understands | — | | `GET /api/protocols?provider=` | The same body plus `provider`: `{ name, adapter, adapterSource, authMode, upstream, modelOverrides: [{ model, adapter, source }] }` — the wire the provider receives and who decided it (`hard-pin`, `operator`, `registry`, `provider-default`), with up to 64 models on a different wire (`modelOverridesTruncated: true` past that). No credential or base URL | 400 empty, repeated, over 200 characters, or control characters; 404 no provider with that name | | `POST /api/protocols/plan` | Preview the path a request would take: `{ "model": "...", "inbound": "responses" \| "chat" \| "messages", "features": [...] }` returns each route candidate's request and response path, delivery mode, fidelity, feature effects, and reasons | 400 invalid JSON, unknown field, model over 200 characters, unknown inbound, or more than 24 / unknown features | | `PATCH /api/protocols/settings` | Change protocol settings: `{ "messagesEnabled"?: boolean, "unrepresentable"?: "legacy" \| "reject", "rollout"?: { ...boolean switches } }`. Returns the same body as `GET /api/protocols`. Closing Messages also sets `claudeCode.enabled` to `false` in the same save; opening it writes only `apiSurfaces.messages.enabled` | 400 invalid JSON, empty body, unknown field, wrong type, or `rollout.managedMessagesNativeOAuth` without `rollout.managedMessagesNative`; 409 configuration busy; 500 save failed (nothing changes) | A preview is computed from configuration alone. It sends nothing to any provider, costs nothing, does not advance combo rotation, and is not logged. The API page in the dashboard shows the same preview under **Request path preview**. A delivery mode of `native` describes how the request travels; it is not a compatibility verification. The `?provider=` form backs the **Upstream wire** section of a provider's settings. It reports the format opencodex sends to that provider; it does not open or close any client API. To change the provider-wide adapter, save the provider's settings as usual (`PATCH /api/providers`). `PATCH /api/protocols/settings` is the only writer here and backs the Messages toggle on the API page. The CLI drives these routes with `ocx api protocols`, `ocx api explain` and `ocx api policy`. The rollout switches are staged and default off ([Protocol paths](/guides/protocol-paths/#rollout-switches)); see [API surfaces](/reference/configuration/server/#api-surfaces-apisurfaces) for how the Messages setting interacts with `claudeCode.enabled` across upgrades and downgrades. ### Health during local credential updates When an asynchronous native-profile update waits for another local process to release the credential-publication lock, `/healthz` can still answer. The update keeps its existing 10-second lock-acquisition deadline and starts writing only after it owns the lock. ### Home identity and the served-by header `GET /healthz` includes `instanceId`, this install's opaque Home id: `home_` followed by 32 hex characters, generated at random once per install. It is the same value as `producer.homeId` in `GET /api/quota-pool`, it stays the same across restarts, and it is never a hostname or derived from one. Every response to `GET /v1/models` carries the same value in the `x-opencodex-served-by` header, so a client can tell which Home answered without reading logs. A Remote Link Child relays the Home's header unchanged, and a Hub-mode client's Codex reads the Hub's response directly, so on any device the header names the Home that served the model list. `GET /readyz` lists `served-by-header` in `features` when the build sends it. Right after a fresh install starts, before its identity file exists, or when that file is unreadable, both the `instanceId` field and the header are left out; an empty value is never sent. Deleting `quota-pool-identity.json` from the OpenCodex home rotates the id together with every quota-pool account reference when the proxy next starts; a running proxy keeps reporting the id it already read. ### Providers | Method and path | Purpose | Notable errors | | --- | --- | --- | | `GET /api/providers` | List redacted provider configuration and discovery state | — | | `POST /api/providers` | Add or replace one validated provider and optionally make it default | 400 invalid/dangerous destination or config; 409 namespace collision | | `PATCH /api/providers?name=...` | Update allowed provider fields (including a merged `headers` block), enabled/default state, or OpenAI account mode | 400 invalid field or transition; 404 unknown provider | | `DELETE /api/providers?name=...` | Delete a provider, reassigning the default when possible | 404 unknown provider; 409 `last_provider`; 409 `provider_has_dependent_combos` | | `POST /api/providers/test?name=...` | Perform a bounded live provider connectivity/model-discovery probe | 404 unknown provider; failures are normally returned as `ok: false` evidence | | `GET /api/provider-quotas` | Read provider quota reports; `refresh=1` forces refresh | — | | `GET /api/quota-pool` | Read the passive `ocx.quota-pool/1` account quota pool (per-account and pooled windows, opaque account references) from cached evidence only; never probes or refreshes, and ignores `refresh`. Pooled windows are a plan-weighted estimate over the routable accounts' readings from the last 30 minutes, plus an `availability` window while no account can run. Also readable from a Remote Link Child or Hub client at `/api/machine/hub-relay/api/quota-pool` | — | | `GET /api/quota-resets` | List recently detected quota-window resets and whether detection is enabled; `limit=` caps the count | 400 invalid `limit` | | `GET /api/fallback` | Read the `ocx.fallback/1` fallback state: effective global switches, provider and route overrides, devices with local fallback permission, and the last 20 fallbacks taken or refused. Also readable from a Remote Link Child at `/api/machine/hub-relay/api/fallback` (link aliases omitted) | — | | `PUT /api/fallback` | Set or clear switches: one write `{ scope: "global"\|"provider"\|"route"\|"device", key?, setting: "model"\|"provider"\|"localFallback", value: true\|false\|null }`, or `{ writes: [ … ] }` with up to 8 applied in one config mutation; `localFallback` is per device; a device key may be a link alias. Returns the new state | 400 invalid body; 404 `unknown_device` (nothing written); 409 `config_unavailable` | | `GET, PUT /api/provider-context-caps` | Read or update global, all-provider, or one-provider context caps | 400 invalid request; 404 unknown provider | | `GET /api/provider-presets` | Return GUI provider presets derived from the runtime registry | — | Provider reads include the optional boolean `inferContextWindow` when configured. Provider PATCH accepts only a boolean or `null` to clear this setting; omission preserves it. A same-name POST also preserves an omitted setting, including the latest stored `false`; an explicit submitted boolean wins. See [Context windows on custom providers](/reference/configuration/providers/#context-windows-on-custom-providers) for its default-off, custom-provider-only behavior. When Antigravity's quota-summary endpoint has no usable response, quota reports may also include per-model Cloud Code Assist usage windows when the model-discovery response provides them. These measurements are diagnostic; an absent model window does not establish that the model is unavailable. For a row using the `claude-cli` adapter, the report is the last recorded Claude subscription observation (`observed: true`) rather than an active probe, and only for the account Claude Code is signed in to. `refresh=1` re-reads the local sign-in and that snapshot. Fetching this Claude CLI report never spawns the CLI or calls Anthropic; other configured providers can still run their normal quota probes. The row is absent until a usage check records quota windows for the signed-in account. A sign-out or account switch clears it at once with `refresh=1` and within a minute (the sign-in cache) on a normal cached read. A newer recorded observation, including one without windows, replaces it on the next read. Passive reads use the last recorded sign-in and snapshot without resolving credentials or probing providers, so an external sign-in change appears after another operation records it. `GET /api/quota-pool` reads no sign-in of its own: it lists the Claude CLI account only for the sign-in this proxy last read, and only when that account has a recorded snapshot. After an external sign-out or account switch it keeps the previous account until the dashboard or a Claude turn reads the sign-in again; after a restart the row is absent until such a read. With `quota=1`, an Anthropic or Antigravity account row whose probe returned no quota carries `quotaUnavailable: true` and, when the cause is known, a closed `quotaFailure` code: `account_unavailable` (sign the account in again), `access_denied`, `rate_limited`, `timeout`, `transport_error`, `upstream_error` or `response_unusable` (retry later), among others. The code never includes upstream text, and a quota failure never changes the row's `health`. The provider context-cap response includes `caps` (active limits) and `values` (last selected values, retained while disabled). Enabling a provider without `value` restores its selection, or uses the global `contextCapValue` on first enable. This also applies to OpenAI: the switch does not select a special 922k mode. An active cap bounds every native window; models with a supported long-context window may expand only up to their own supported ceiling. Updating the global value with `{ "value": 600000, "setAll": true }` changes only enabled provider caps; disabled providers keep their remembered selections when later enabled. In contrast, `{ "setAll": true }` without `value` enables every configured provider at the current global value, replacing their remembered selections. Turning a cap off does not activate its remembered value or erase the selection. `provider_has_dependent_combos` is a safety barrier: remove or edit the dependent combos before deleting their provider. ### Sidebar and consent-bound actions | Method and path | Purpose | Notable errors | | --- | --- | --- | | `GET /api/github/star` | Read repository star status through the user's `gh` session | Status-specific fixed result codes | | `POST /api/github/star` | Star the repository only from an authenticated human action | 403 `agent_consent_required` for agent-driven callers without dashboard-session evidence | | `GET /api/update/badge` | Read cached package badge without a registry lookup; missing, wrong-channel or 40-hour-old cache returns `unknown: true`. `surface=desktop&session=` reads only that desktop app session. | 400 invalid surface; missing or expired desktop session returns `unknown: true` | | `POST /api/update/desktop-snapshot` | Desktop shell publishes its Tauri-updater display state through the bound proxy client | 403 if an `Origin` header is present or the principal is not the raw `admin-token`; 400 invalid fields; 413 over 1 KiB | The desktop snapshot is temporary display state, not an install request. The proxy stores at most 32 sessions in memory and expires one 180 seconds after its last heartbeat. A normal browser without surface=desktop continues to read the package badge. The proxy checks an eligible package install after startup when its cache is missing or older than 20 hours, and checks freshness hourly. Set `OCX_DISABLE_UPDATE_CHECK=1` to disable automatic checks. Explicit check and run requests still work. :::caution Management authentication proves access to the proxy; it does not prove consent to spend the user's identity. An agent must not route around `agent_consent_required`. The user must choose whether to star the repository. ::: ### System lifecycle `POST /api/system/restart` keeps the 60-second drain by default, including requests with no body or `{}`. An authenticated caller can explicitly send a JSON body such as `{"drainGraceMs":2000}` to choose a shorter active-request/scoped-drain grace. The value must be an integer from 1 to 60000 milliseconds. Invalid bodies or values return 400 before starting a drain; the standard management-body limit still applies. The target-bound local restart capability retains the default grace; setting this body option requires a management session or admin token (otherwise 403). The response's `drainTimeoutMs` reports the accepted grace. Repeated calls retain the first accepted restart's grace and do not change its deadline. Grace is measured from acceptance, including the response-flush delay. The cleanup watchdog remains 60 seconds and replacement readiness retains its separate 70-second budget. A short grace can interrupt a turn that already executed upstream. Check its outcome before resubmitting; OpenCodex adds no automatic replay of ambiguous work, and a healthy replacement does not prove resending is safe. The dashboard, CLI, tray and automatic restarts continue using the 60-second default. During a restart drain, new data-plane requests receive HTTP 503 with JSON `error.type: "server_error"`, `error.code: "server_restarting"`, and the message "OpenCodex is restarting; retry this request." Responses retain `Retry-After: 5` and the receiving listener's CORS policy. This code lets every Codex version retry the 503 without reporting model capacity; provider overload errors retain their separate mapping. | Method and path | Purpose | Notable errors | | --- | --- | --- | | `GET /api/system/memory` | Return scalar process, heap, stream, response-state, watchdog, and active-turn metrics. Response-state diagnostics include spill-write status, consecutive failures, fixed privacy-safe failure class, and last failure/success timestamps. `spillLastWriteFailureOrigin` is `retry_returned_timeout`, `timeout_memo_refusal`, or null; cumulative `spillAclRetryReturnedTimeouts` and `spillAclTimeoutMemoRefusals` count terminal failed publications; cumulative `spillCapacityRefusals` and `spillHeadroomEvictions` count continuations refused at the spill ceiling and continuations evicted to make room for a newer one. See [Windows spill diagnostics](/troubleshooting/windows-memory/) for process-local semantics. Raw errors and paths are never returned. | — | | `POST /api/system/restart` | Begin a drain-aware process restart without removing client injection; optional JSON `drainGraceMs` explicitly shortens the default 60s grace | Returns 202; repeated calls report the existing grace; 400 invalid body or grace | | `POST /api/stop` | Stop the service, restore native Codex, remove managed Grok injection, and drain the proxy | 409 service ownership conflict; 409 `respawnable_service` when a Windows Task Scheduler wrapper could respawn the proxy and the caller is not `ocx stop` (nothing is changed); 409 `self_unload_service` when this proxy is running as the installed launchd/systemd service, because stopping the manager from inside it would end the process before native Codex is restored — run `ocx stop` instead (nothing is changed); 409 when the installed manager refuses to stop; 409 `service_state_unknown` when the Task Scheduler state cannot be read (nothing is changed; repair the query and retry), or when the Windows checked service stop does not finish within the route's cap (6 s; 4 s for a leftover wrapper of a deleted task). On Windows a request from `ocx stop` whose receipt records that the CLI already ran the checked service stop does not repeat it | | `GET /api/system/codex-app-server` | Report whether running Codex app-servers predate the current model catalog | — | | `POST /api/system/codex-restart` | Refresh the catalog, then restart Codex app-servers. A running Codex desktop app is given a restart attempt so the model picker can reload; the `desktopApp` response fields report a refusal, surviving targets, or a failed relaunch. A shell newer than the catalog is still reported as `desktopApp.pickerState: "unknown"`, because its start time cannot prove which `model_catalog_json` binding it loaded; an earlier sync may have rebound an already-existing catalog. A shell no newer than the catalog, or one whose binding this request changed, is `stale`. A closed desktop returns `desktopApp.reason: "no_targets"`; its `pickerState` may be `not_running`, or `stale` when this request changed the catalog binding. When the proxy itself is running inside the Codex app, the desktop restart is refused rather than handed off. | Returns 200 with `code: partially_stopped` when a target survives | ### Codex authentication delegation `GET /api/settings` reports the effective `codexAccountPickerEnabled` boolean. A `PUT` containing that strict boolean initializes privacy-safe account selectors when enabling an empty map, preserves existing selector labels when disabling or re-enabling, persists first, and then requests one bounded catalog convergence only when effective picker visibility changed. The successful response includes `catalogRefreshPending`: `false` means the catalog commit completed (or no refresh was needed), while `true` means the setting was saved but `POST /api/sync` should be used to retry the catalog refresh. Persistence or selector-allocation failure rolls the in-memory settings back and does not run convergence. The root management dispatcher delegates every `/api/codex-auth/*` request to the Codex account manager. Its routes are: | Method and path | Purpose | Notable errors | | --- | --- | --- | | `GET, POST, DELETE /api/codex-auth/accounts` | List/refresh or delete Codex accounts. POST is retained as a disabled compatibility endpoint; successful DELETE responses include `catalogRefreshPending`. | POST always returns 403 `manual_import_disabled`; 400 invalid DELETE input | | `PUT /api/codex-auth/accounts/alias` | Set or clear an account alias | 400 invalid account/alias | | `PUT /api/codex-auth/accounts/pause` | Manually pause or resume an account and its existing matching main/pool entries; returns `affectedAccountIds` | 400 invalid account/state; 404 missing account; 503 main identity busy or unreadable | | `PUT /api/codex-auth/accounts/pause-exhausted` | Pause accounts whose quota is exhausted | Mutation-lock failures become 503 | | `PUT /api/codex-auth/accounts/credits` | Allow or stop spending ChatGPT credits after the usage limit. Body `{ id, creditsAfterLimit }` for one account, including `__main__`: true adds the id to `creditCodexAccountIds`, false removes it. Body `{ all }` for the global switch: true lists `__main__` and every pool account, false clears the list. Applies to the next selection. | 400 invalid id or non-boolean value; 404 missing account | | `PUT /api/settings` with `codexQuotaAutoRefresh: { id, window, enabled }` | Enable or disable 5-hour or weekly automatic window activation for one account | 400 invalid id/window/state; 404 missing account; 409 unavailable window | | `POST /api/codex-auth/accounts/clear-cooldown` | Clear runtime cooldown for one account or all accounts | 400 invalid id | | `GET, PUT /api/codex-auth/active` | Read or select the active account | 400 invalid or missing account; 409 paused/legacy-row conflict or `account_selection_unavailable` | | `PUT /api/codex-auth/auto-switch` | Set the global quota threshold with `{ threshold }`, or an account override with `{ id, threshold }`; `null` restores global inheritance, and `__main__` selects the Desktop login | 400 invalid id/threshold; 404 missing account | | `GET /api/codex-auth/preserve-signed-in` | Read policy, current `affectedAccountIds`, `identityKnown`, `nextAccountId`, `nextUsesSignedInQuota` (actual next choice, even when disabled), `pinnedAccountId`, `bindings`, `priorityFailbackEnabled`, and `fallbackConsumesSignedInQuota` | 503 native profile busy/unreadable | | `PUT /api/codex-auth/preserve-signed-in` | Strict `{ enabled: boolean, applyToBound?: boolean }`; explicit `applyToBound: true` requires enabled, releases affected bindings/pin for next request; reports `releasedPin` | 400 invalid body; 503 native profile busy/unreadable | | `PUT, PATCH /api/codex-auth/pool-strategy` | Update Codex account-pool selection strategy | 400 invalid strategy/config | | `PUT /api/codex-auth/failover` | Set the account failover threshold | 400 invalid threshold | | `GET /api/codex-auth/quota` | Read cached quota state by account | — | | `GET /api/codex-auth/low-quota-events?limit=20` | Read only this server’s last 0–100 low-quota log/notice and pause-save events (default 20); includes account id and status (`logged` for the default log-only alert or a host without a supported notifier; `delivered` when the opted-in OS notifier accepted the notice; `failed` when it failed or timed out; `cancelled` when its episode ended first; `succeeded` for a completed pause save) | 400 invalid limit; management authentication required | | `GET /api/codex-auth/reset-credits` | Inspect reset-credit eligibility for an account | 400 missing account id; upstream status passthrough; 500 lookup failure | | `POST /api/codex-auth/reset-credits/consume` | Consume an eligible reset credit. Optional `operationId` (UUIDv4) makes the redemption idempotent: the same id replays one durable outcome instead of spending a second credit. | 400 missing account id or invalid `operationId`; 409 `identity_mismatch` when the id belongs to another account; upstream status passthrough; 503 `server_busy`, `capacity`, or `unavailable`; 500 consume failure | | `POST /api/codex-auth/login` | Start Codex login or reauthentication | 400 invalid request; conflict/busy login states | | `POST /api/codex-auth/login/code` | Submit a manual code for a Codex login flow | 400 invalid flow/code | | `POST /api/codex-auth/login/cancel` | Cancel only the pending Codex login identified by `{ "flowId": "..." }` | 400 missing, unknown, or non-pending flow ID | | `GET /api/codex-auth/login-status` | Poll a flow or account login state. A completed new-account flow includes `catalogRefreshPending: true` only when recovery is needed. | Unknown flows report `expired`; no active flow reports `idle` | `PUT /api/codex-auth/active` requires `{ "accountId": "" }` or an explicit `{ "accountId": null }` to clear selection. Re-selecting the current account is an explicit selection even if another process changed the saved account. The server preserves unrelated saved settings and rejects targets removed or paused since the dashboard loaded. An unavailable or invalid saved configuration leaves the previous live selection and affinity unchanged; reload settings before retrying. A successful response describes the committed selection. Existing quota and failover rules can still release a pin; `pinDrained` reports a currently known drain reason. For reset-credit consumption, a different `operationId` supplied while the same physical account has an unfinished operation joins that operation as an alias. Its retry uses the original upstream request ID and records the outcome under that same identity, so later requests with the original ID or a known alias replay the stored result without another consume request. A previously unseen ID supplied after settlement starts a new explicit redemption; clients retrying an existing action should keep its ID. After a confirmed manual `reset`, OpenCodex checks fresh usage for that same account and can reconcile its eligible pre-existing shared reset-derived cooldown immediately. Paused accounts, accounts requiring reauthentication and cooldowns already owned by an in-flight probe remain excluded from this recovery; their cooldowns are retained. Usage started before the reset, incomplete or exhausted usage, a changed account, and a newer quota failure do not qualify. Older main-account usage responses cannot replace a newer published observation. If usage needs credential refresh, recovery requires that refresh's confirmed lineage; an externally replaced credential does not qualify merely because it belongs to the same account. Explicit `Retry-After`, Reserve cooldowns, pause settings, pins and the selected account are preserved. `already_redeemed` and durable replay do not prove a new reset and do not gain this recovery behavior. A failed or busy usage refresh after a confirmed `reset` or `already_redeemed` does not turn the completed consumption into an error: the response remains HTTP 200 with its consume `code`, omitting `remaining` when no fresh count was obtained. This response confirms the consume outcome, not that the account is now routable. Refresh usage to check availability; do not consume another credit to retry a failed usage refresh. If a new account config row is saved but credential setup cannot finish, OAuth `login-status` reports `status: "error"` with `code: "codex_credential_persistence_failed"`, `accountId`, `needsReauth: true`, and optional `catalogRefreshPending: true`; storage-error details are not exposed. The account row remains saved: reauthenticate or delete it before retrying account creation. Configuration-writer or credential-refresh lock timeouts under this delegated family return HTTP 503 with code `CONFIG_MUTATION_LOCK_UNAVAILABLE`. Clients should retry shortly rather than treating that response as a permanent account failure. Account creation and deletion commit credentials/configuration before catalog convergence. A failed or deferred catalog attempt never rolls back the durable account mutation and never reflects internal provider, account, path, or credential details; clients receive only the completion boolean. Deleting an account retains its selector binding so exact routes fail closed while the account is absent and the same selector is restored if that account id is added again. ## Desktop authorization Desktop compatibility mutations require a Desktop-purpose one-use grant in addition to a current local dashboard session. On the proxy computer, run `ocx gui pair --desktop --origin ` using the panel's exact loopback origin, then submit its code in the panel. An ordinary `ocx gui pair` code or an already paired session does not supply Desktop scope. A current automatically issued loopback session can receive this scope after a valid Desktop grant exchange; it does not need to become an operator-paired session. `POST /api/codex/desktop-compatibility/authorization` accepts exactly `{ "grant": "" }` and, on success, returns HTTP 200 with `{ "ok": true, "authorized": true }`. It adds scope to the existing browser session without issuing or replacing its session credentials. Malformed JSON or body shape returns 400; a refused exchange returns 403 `desktop_authorization_required`. The grant must be unused, unexpired, Desktop-purpose and bound to this standalone local origin. Raw admin tokens, remembered-admin sessions, Hub and connected-client contexts cannot exchange it. On the proxy computer, a separate private browser window at the same eligible local origin can obtain a fresh loopback session and redeem a new grant. The panel then calls `GET /api/codex/desktop-compatibility/authorization`. After common management admission, this read returns HTTP 200 with `{ "ok": true, "supported": boolean, "authorized": boolean, "rememberedSession": boolean }`, including when Desktop scope is absent (`authorized: false`) or the request context is unsupported (`supported: false`, `authorized: false`). Missing or expired management credentials can still fail at the common authentication boundary; the GET does not bypass that boundary or return a route-specific `desktop_authorization_required` error. Desktop scope lasts at most five minutes and no longer than the current session. It does not renew automatically, establish general pairing, or change Remote Link and data-key disclosure permissions. The panel verifies scope, refreshes certificate/runtime status and the startup-setting revision, and requires a fresh action and consent. Authorization never replays an earlier mutation. Certificate, runtime and settings POSTs recheck scope and return 403 `desktop_authorization_required` when it is unavailable. ## Windows compatibility certificate setup `GET /api/codex/desktop-compatibility/certificate` returns public certificate status: support, state, fingerprint, expiry, renewal notice, trust observation and any active operation. The certificate response also reports `mutationAuthorized` for the current session and ingress; this flag is read-only guidance, and each mutation checks authorization again. It never generates a key, decrypts private material or registers OS trust. Certificate trust alone does not mean a compatibility relay is running or the private key has been verified in this process. POST accepts `action: "prepare" | "trust" | "remove-trust" | "renew"` and `confirmed: true`. Trust actions also require the exact uppercase SHA-256 `fingerprint` returned by status. These mutations require a current GUI session with [Desktop authorization](#desktop-authorization) on trusted standalone loopback ingress. An admin token or a session without Desktop scope receives 403 `desktop_authorization_required`. No session mutates before that step-up succeeds: an automatically issued loopback session is a valid subject for the grant exchange, but it is refused here until it consumes one, so the grant carries the consent rather than the session's issuance mode. The exchange itself refuses a remembered dashboard session before it reads the body, because that cookie proves the durable admin token rather than the operator's presence at this machine. These actions are intended for a local confirmation flow, not unattended certificate enrollment. Prepare stores a constrained 30-day authority with a Windows CurrentUser-DPAPI-protected private key. Subsequent preparations reuse it. Trust actions never create missing state or silently replace an expired root. Removal refuses while Codex is running or process ownership cannot be established. Cancellation or uncertain OS command completion is checked against the actual certificate store. Unknown state remains an error rather than authorizing an automatic retry. Replies contain no PEM, private keys, account data or subprocess output. Renewal requires the current fingerprint and an absent Codex app. It verifies removal of the old certificate's trust before publishing a validated encrypted replacement. Refused or uncertain removal preserves the old identity. The replacement is prepared but untrusted; register it with a separate `trust` confirmation using its new fingerprint. A stale retry cannot replace the new identity again. No certificate backup chain is retained. This setup API does not enable a relay, change login, alter usage, restart Codex or install a watcher. CurrentUser protection does not isolate secrets from other processes running as the same OS user. ## Experimental Windows compatibility runtime `GET /api/codex/desktop-compatibility/runtime` is an inert status read. POST requires a current local GUI session with [Desktop authorization](#desktop-authorization) — that session is refused until it consumes a Desktop-purpose grant — and `{ action, confirmed: true }`, where action is `start`, `stop`, `observe`, `launch`, or `apply`. Only `apply` additionally requires `accountWideConsent: true`. The endpoint is experimental. The dashboard exposes it under **Codex Set → Desktop compatibility**; the **Resume observation when OpenCodex starts** toggle saves the optional `desktopCompatibility.startOnProxyStart` preference. OpenCodex managed client mode does not offer these local controls or forward them to the shared hub. Open the dashboard at the configured loopback origin and complete the [Desktop grant exchange](#desktop-authorization) with the panel's `ocx gui pair --desktop --origin ""` command. The code is a Desktop-purpose grant: it adds Desktop scope to the current browser session for at most five minutes and does not create a general pairing session. Controls stay disabled until that scope is verified; neither the grant nor the exchange changes certificate trust, runtime state or the auto-start preference. Start requires an already prepared, trusted certificate, a freshly verified native file-based ChatGPT login and an official Microsoft Store Codex package for the current Windows user. Windows must verify the signed package contents and report a valid OpenAI Authenticode signature for the installed `ChatGPT.exe`. Failure or unavailable proof returns `build_unverified`. Observation starts in Observe mode. HTTP/HTTPS and authenticated SOCKS5 outbound proxies use the same explicit selection for HTTP, identity verification and upgraded sockets. NO_PROXY is honored; failures never retry directly. An invalid or unsupported setting returns `egress_proxy_invalid`. Start never registers a certificate or changes login. Launch refuses an app that is already running. It checks the verified full package name and executable SHA-256 before package activation, then checks the process image and routing argument before reporting success. A refused or indeterminate package activation stops the compatibility runtime, closes its managed connections, and revokes the account-wide trial. This also applies to a managed Codex restart. OpenCodeX leaves any PID returned by activation alone. To run another trial, start observation again, wait for a fresh eligible exhaustion snapshot, and explicitly consent to a new Apply request. PAC and CONNECT ports are persisted after successful first binding and reused on restart. `connection_unavailable` means binding failed; `connection_invalid` or `connection_changed` means stored endpoint identity could not be accepted. These failures never silently rotate ports or overwrite the existing connection record. Restart returns to Observe, not Apply. `native_routing_unverified` means the native root/profile routing cannot be matched to this process's bound OpenCodex listener. Runtime status may expose `contextFailure` for this condition or `build_unverified`. These states disable response correction without claiming an app repair. A status response can also carry `buildAssessment`, the public metadata of the last completed build check: `assessedVersion` (the baseline holding native acceptance evidence), `observedVersion`, `verified` and `completedAt`. It records a past observation, not a live install reading: a stopped runtime, an app update or a pending or interrupted check can leave it older than the installed package, and only a completed check replaces it. `observedVersion` is null unless discovery matched the assessed package family and entry point; an identified build keeps its own version, and `verified` reports whether the package passed its official package proof at `completedAt`, never whatever is installed later. The field is absent until the service creates its probe during start and `null` until that probe finishes a check; reading status never starts one. Apply requires a recently observed eligible exhaustion snapshot and lasts at most three minutes at the response layer. It changes two account-UI gate flags, not usage percentages, credits, spending restrictions or server limits. The usage response does not identify the selected model: this trial cannot promise an effect limited to external models. An accepted activation or produced response does not prove the app accepted the new snapshot or enabled its composer. An available or protected original usage record returns the controller to Observe and invalidates pending corrections. Later exhaustion requires another explicit Apply request. Changed root TOML or configured model/provider/fallback routing invalidates the runtime's observation context until stop/start; reverting those settings does not reactivate it. Observe disarms correction and refreshes only validated usage streams. Stop closes this runtime's listeners and connections; the PAC includes `DIRECT` fallback. The certificate stays installed for reuse. Stop the runtime and close Codex before removing trust or renewing the certificate. Failed cleanup reports `cleanup-required`; it does not claim that the runtime is off. OS login, system proxy settings and application files are not modified by these runtime commands. The separate settings endpoint returns `{ startOnProxyStart, revision }`. POST requires `{ startOnProxyStart: boolean, revision, confirmed: true }` from a current GUI session with [Desktop authorization](#desktop-authorization) on trusted standalone loopback ingress; a session without Desktop scope receives 403 `desktop_authorization_required`. A stale revision refuses the write; a valid update preserves unrelated config fields and verifies the persisted result. This preference affects the next proxy start, never current runtime state, app launch or an Apply trial. An uncertain response must be followed by GET, not an automatic POST retry. Invalid or missing configuration is preserved rather than recreated. ## Choosing a client For ordinary administration, the [Web Dashboard](/guides/web-dashboard/) gives the safest guided workflow. For headless hosts and automation, use the corresponding `ocx` commands: they call this same live API and return a nonzero result when the proxy is unreachable or the operation fails. Direct HTTP is most useful for integrations that need the exact endpoint contracts above. ## Remote sessions and data-key rotation `POST /api/keys/rotate {id}` starts a ten-minute overlap and returns the new data secret once. `POST /api/keys/rotate/commit {id,rotationId}` commits it; `DELETE /api/keys/rotate {id,rotationId}` aborts it. All require management authentication; data keys cannot call them. `POST /api/session/logout` requires the current `gui-session`, matching Origin, and CSRF. An admin token receives 403 and can never mint or exchange into a consent session. ## Anthropic account usage threshold `PUT /api/oauth/accounts/auto-switch` Anthropic OAuth only; `{ provider: "anthropic", accountId, threshold }` accepts integer 0–100 or null to inherit. Missing threshold is invalid. Stored override survives restart and is removed with the account. Account-list DTOs include `autoSwitchThresholdOverride` (integer/null), `autoSwitchThreshold` (pool default), and `effectiveAutoSwitchThreshold`. 0 disables usage-driven switching only; it never disables pause or 429 recovery. HTTP: 400 invalid/unsupported; 404 missing account; `oauth_mutation_busy` on lock contention. ### Forced Claude Code subagent model The Subagents page offers **Force all subagents onto one model**, off by default. Select an exposed roster-style id, such as `combo/tev-auto`, then enable the switch. The roster is offered first; unavailable saved roster entries cannot be force targets. `ocx agent subagents force combo/tev-auto` sets `claudeCode.subagentModelForce`; `ocx agent subagents force -` clears it. `ocx agent status` reports the setting. `GET /api/subagent-models` returns `force`, `forceAvailable`, and `forceStatus`; `PUT` accepts `{ "force": "combo/tev-auto" }` or `{ "force": null }` without changing the roster. Omitting `force` leaves it unchanged. Invalid or unexposed targets are rejected on write; stale targets are reported and skipped at launch. This takes effect on the **next routed `ocx claude` launch**, injecting `CLAUDE_CODE_SUBAGENT_MODEL` as an explicit proxy alias (with `[1m]` only for an authoritative million-token window; native Claude targets use a reversible native alias) and `CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1`. Each nonempty shell-exported variable independently wins. Native launches inject neither variable; plain `claude` is not affected. No plugin files or `settings.json` are modified by this setting. Claude Code **2.1.257 or newer** is required for FORCE. Plugin and built-in agents (including Explore/Plan) and per-call model arguments are overridden. Forks and subagent skills with `model: inherit` keep the main conversation model. The main loop and Haiku/small-fast sidecars are unaffected. Existing roster files remain available. The dashboard warns about old or unknown CLI versions, unavailable targets, and either variable already present in `settings.json` → `env` (which overrides launch env). Detection is read-only and server-local: it cannot inspect another launch shell, another machine, or project-local settings. An unknown result is not proof of force support.