{"openapi":"3.1.0","info":{"title":"BitRouter API","description":"The BitRouter API exposes the routing proxy and account-bound services of the hosted BitRouter Cloud node.\n\n## Base URL\n\n```\nhttps://api.bitrouter.ai\n```\n\nMost endpoints are served under `/v1`. The healthcheck (`/ping`) lives at the root.\n\n## Authentication\n\nRouting endpoints (`/v1/chat/completions`, `/v1/messages`, `/v1/responses`, `/v1beta/models/{model_action}`) accept either:\n\n- `x-api-key: <api-key>` — Anthropic-compatible header.\n- `Authorization: Bearer <api-key | JWT>` — issued via the BitRouter console or minted from a wallet (CAIP-10 issuer).\n\nDiscovery endpoints (`/v1/models`, `/v1/providers`, `/v1/byok/encryption-pubkey`), the healthcheck, and the scraper-facing `/metrics` are public.\n\n## Multi-Protocol Routing\n\nBitRouter accepts requests in the native format of each supported provider:\n\n- **OpenAI Chat Completions** — `/v1/chat/completions`\n- **OpenAI Responses** — `/v1/responses`\n- **Anthropic Messages** — `/v1/messages`\n- **Google Generative Language** — `/v1beta/models/{model}:generateContent`\n\nThe router resolves the requested model to a configured upstream provider, forwards the request, and returns the response in the same provider format.","version":"1.0.0"},"servers":[{"url":"https://api.bitrouter.ai","description":"Production"}],"paths":{"/ping":{"get":{"tags":["Health"],"summary":"Liveness check","description":"Returns `200 OK` with an empty body if the node is up.","operationId":"ping","responses":{"200":{"description":"Node is up."}}}},"/v1/models":{"get":{"tags":["Discovery"],"summary":"List available models","description":"Returns all models available across configured providers. Supports optional query filters for provider, model ID substring, and modality.","operationId":"listModels","parameters":[{"in":"query","name":"provider","description":"Filter by provider name (exact match against the model's `providers` array).","schema":{"type":"string"},"style":"form"},{"in":"query","name":"id","description":"Filter by model ID (case-insensitive substring match).","schema":{"type":"string"},"style":"form"},{"in":"query","name":"input_modality","description":"Filter by supported input modality (e.g. `text`, `image`).","schema":{"type":"string"},"style":"form"},{"in":"query","name":"output_modality","description":"Filter by supported output modality.","schema":{"type":"string"},"style":"form"}],"responses":{"200":{"description":"List of models.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ModelListResponse","description":"Envelope shape for `GET /v1/models`. Wraps the catalogue in `{ \"data\": [...] }`\nso future top-level fields (pagination cursors, etc.) can be added without a\nbreaking change.","type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/$defs/ModelResponse"}}},"required":["data"],"$defs":{"ContextTier":{"description":"A higher context-pricing bracket. Some upstreams bill a model at a steeper\nrate once the prompt crosses a context-length threshold (e.g. one rate up\nto 128k input tokens, a higher one between 128k and 256k). The selected\nbracket's rates apply to the **whole** request — a step function, not\ngraduated marginal brackets — and the bracket is chosen by the request's\ntotal input (prompt) token count.\n\nUpstreams that publish such tiers:\n- Alibaba Qwen Model Studio:\n  <https://help.aliyun.com/en/model-studio/models>\n- Google Gemini API long-context pricing:\n  <https://ai.google.dev/gemini-api/docs/pricing>","type":"object","properties":{"above_input_tokens":{"description":"**Exclusive** lower bound on total input tokens. A request whose input\nsize is strictly greater than this is eligible for the bracket; a\nrequest exactly at the bound stays in the lower bracket (so a base\nbracket documented as \"≤ 128k\" is expressed as a tier with\n`above_input_tokens: 128000`).","type":"integer","format":"uint64","minimum":0},"input_tokens":{"$ref":"#/$defs/InputTokenPricing"},"output_tokens":{"$ref":"#/$defs/OutputTokenPricing"}},"required":["above_input_tokens"]},"InputTokenPricing":{"description":"Input token pricing per million tokens.","type":"object","properties":{"cache_read":{"description":"Cost per million cache-read input tokens.","type":["number","null"],"format":"double"},"cache_write":{"description":"Cost per million cache-write input tokens.","type":["number","null"],"format":"double"},"no_cache":{"description":"Cost per million non-cached input tokens.","type":["number","null"],"format":"double"}}},"ModelFirstTokenLatencyResponse":{"type":"object","properties":{"best_p50_ms":{"type":["integer","null"],"format":"uint64","minimum":0},"best_p95_ms":{"type":["integer","null"],"format":"uint64","minimum":0},"sample_count":{"type":"integer","format":"uint64","minimum":0},"window_seconds":{"type":"integer","format":"uint64","minimum":0}},"required":["sample_count","window_seconds"]},"ModelLatencyResponse":{"type":"object","properties":{"first_token":{"$ref":"#/$defs/ModelFirstTokenLatencyResponse"}},"required":["first_token"]},"ModelOutputTokenThroughputResponse":{"type":"object","properties":{"best_p50_tokens_per_second":{"type":["number","null"],"format":"double"},"best_p95_tokens_per_second":{"type":["number","null"],"format":"double"},"sample_count":{"type":"integer","format":"uint64","minimum":0},"window_seconds":{"type":"integer","format":"uint64","minimum":0}},"required":["sample_count","window_seconds"]},"ModelPricing":{"description":"Token pricing per million tokens for a model.\n\n`input_tokens`/`output_tokens` are the **base bracket**: the rates for the\nlowest context range and the fallback when no [`context_tiers`] entry\napplies. When `context_tiers` is empty the pricing is a single flat rate\nfor every request size (the historical behaviour).\n\n[`context_tiers`]: ModelPricing::context_tiers","type":"object","properties":{"context_tiers":{"description":"Optional higher context brackets. Empty ⇒ flat pricing. The registry\nvalidator enforces ascending, unique `above_input_tokens` and a\ncomplete base bracket, so the per-request resolver does not depend on\nlist order.","type":"array","items":{"$ref":"#/$defs/ContextTier"}},"input_tokens":{"$ref":"#/$defs/InputTokenPricing"},"output_tokens":{"$ref":"#/$defs/OutputTokenPricing"}}},"ModelResponse":{"type":"object","properties":{"capabilities":{"description":"Union of inference capabilities advertised across this model's providers\n(e.g. `structured_outputs`). Omitted when empty.","type":"array","items":{"type":"string"}},"description":{"type":["string","null"]},"hosted":{"description":"`true` for a hosted (platform-served) model; `false` for a BYOK/\nBYO-subscription model that only appears when the caller has a key for\none of its providers and requires that key to route.","type":"boolean"},"id":{"type":"string"},"input_modalities":{"type":"array","items":{"type":"string"}},"latency":{"$ref":"#/$defs/ModelLatencyResponse"},"max_input_tokens":{"type":["integer","null"],"format":"uint64","minimum":0},"max_output_tokens":{"type":["integer","null"],"format":"uint64","minimum":0},"name":{"type":["string","null"]},"open_weights":{"description":"`true` when the model's weights are openly licensed, `false` when they\nare proprietary. Omitted entirely for models the registry does not\ndeclare (external BYOK offerings) — an absent field means \"unknown\",\nnever \"proprietary\".","type":["boolean","null"]},"output_modalities":{"type":"array","items":{"type":"string"}},"pricing":{"anyOf":[{"$ref":"#/$defs/ModelPricing"},{"type":"null"}]},"providers":{"$ref":"#/$defs/ProvidersSummary"},"throughput":{"$ref":"#/$defs/ModelThroughputResponse"}},"required":["id","input_modalities","output_modalities","capabilities","hosted","providers","latency","throughput"]},"ModelThroughputResponse":{"type":"object","properties":{"output_tokens":{"$ref":"#/$defs/ModelOutputTokenThroughputResponse"}},"required":["output_tokens"]},"OutputTokenPricing":{"description":"Output token pricing per million tokens.","type":"object","properties":{"audio":{"description":"Cost per million audio output tokens. Reserved — see `image`.","type":["number","null"],"format":"double"},"image":{"description":"Cost per million image output tokens. Reserved — not yet wired\ninto `calculate_charge_micro_usd`.","type":["number","null"],"format":"double"},"reasoning":{"description":"Cost per million reasoning output tokens.","type":["number","null"],"format":"double"},"text":{"description":"Cost per million text output tokens.","type":["number","null"],"format":"double"}}},"ProvidersSummary":{"type":"object","properties":{"total_online":{"type":"integer","format":"uint","minimum":0}},"required":["total_online"]}}}}}}}}},"/v1/providers":{"get":{"tags":["Discovery"],"summary":"List providers","description":"Public registry of providers the node knows about, sourced from the upstream `bitrouter-providers` builtins. Used by the console to render the BYOK page without hard-coding the list.","operationId":"listProviders","responses":{"200":{"description":"List of providers.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ProviderListResponse","description":"Envelope for `GET /v1/providers`. Same `{ \"data\": [...] }` shape as\n`/v1/models` so the two listings stay consistent for SDK consumers.","type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/$defs/ProviderCatalogEntry"}}},"required":["data"],"$defs":{"Access":{"description":"How a caller obtains access to a provider — the registration / credential\nobtainment model. Mirrors the registry `access` field; supersedes the old\n`byok` boolean. Drives the console BYOK page (lists `api_key` only), the\nplatform pool (skips `local_*`), and the BYOK overlay's security gate.\nSerialized on the public `/v1/providers` catalog (`Serialize` + `JsonSchema`)\nso the console can filter the BYOK page on `access === \"api_key\"` directly.","oneOf":[{"description":"Public self-registration → a portable API key (the BYOK case).","type":"string","const":"api_key"},{"description":"Public, credentials minted by a local browser/device OAuth flow.","type":"string","const":"local_oauth"},{"description":"Public, credentials minted by a local OAuth+PKCE flow.","type":"string","const":"local_pkce"},{"description":"No public registration — platform-pooled / invite-only. Never BYOK.","type":"string","const":"private"}]},"ContextTier":{"description":"A higher context-pricing bracket. Some upstreams bill a model at a steeper\nrate once the prompt crosses a context-length threshold (e.g. one rate up\nto 128k input tokens, a higher one between 128k and 256k). The selected\nbracket's rates apply to the **whole** request — a step function, not\ngraduated marginal brackets — and the bracket is chosen by the request's\ntotal input (prompt) token count.\n\nUpstreams that publish such tiers:\n- Alibaba Qwen Model Studio:\n  <https://help.aliyun.com/en/model-studio/models>\n- Google Gemini API long-context pricing:\n  <https://ai.google.dev/gemini-api/docs/pricing>","type":"object","properties":{"above_input_tokens":{"description":"**Exclusive** lower bound on total input tokens. A request whose input\nsize is strictly greater than this is eligible for the bracket; a\nrequest exactly at the bound stays in the lower bracket (so a base\nbracket documented as \"≤ 128k\" is expressed as a tier with\n`above_input_tokens: 128000`).","type":"integer","format":"uint64","minimum":0},"input_tokens":{"$ref":"#/$defs/InputTokenPricing"},"output_tokens":{"$ref":"#/$defs/OutputTokenPricing"}},"required":["above_input_tokens"]},"FirstTokenLatencyMetrics":{"type":"object","properties":{"p50_ms":{"type":["integer","null"],"format":"uint64","minimum":0},"p95_ms":{"type":["integer","null"],"format":"uint64","minimum":0},"sample_count":{"type":"integer","format":"uint64","minimum":0}},"required":["sample_count"]},"InputTokenPricing":{"description":"Input token pricing per million tokens.","type":"object","properties":{"cache_read":{"description":"Cost per million cache-read input tokens.","type":["number","null"],"format":"double"},"cache_write":{"description":"Cost per million cache-write input tokens.","type":["number","null"],"format":"double"},"no_cache":{"description":"Cost per million non-cached input tokens.","type":["number","null"],"format":"double"}}},"ModelPricing":{"description":"Token pricing per million tokens for a model.\n\n`input_tokens`/`output_tokens` are the **base bracket**: the rates for the\nlowest context range and the fallback when no [`context_tiers`] entry\napplies. When `context_tiers` is empty the pricing is a single flat rate\nfor every request size (the historical behaviour).\n\n[`context_tiers`]: ModelPricing::context_tiers","type":"object","properties":{"context_tiers":{"description":"Optional higher context brackets. Empty ⇒ flat pricing. The registry\nvalidator enforces ascending, unique `above_input_tokens` and a\ncomplete base bracket, so the per-request resolver does not depend on\nlist order.","type":"array","items":{"$ref":"#/$defs/ContextTier"}},"input_tokens":{"$ref":"#/$defs/InputTokenPricing"},"output_tokens":{"$ref":"#/$defs/OutputTokenPricing"}}},"OutputTokenPricing":{"description":"Output token pricing per million tokens.","type":"object","properties":{"audio":{"description":"Cost per million audio output tokens. Reserved — see `image`.","type":["number","null"],"format":"double"},"image":{"description":"Cost per million image output tokens. Reserved — not yet wired\ninto `calculate_charge_micro_usd`.","type":["number","null"],"format":"double"},"reasoning":{"description":"Cost per million reasoning output tokens.","type":["number","null"],"format":"double"},"text":{"description":"Cost per million text output tokens.","type":["number","null"],"format":"double"}}},"OutputTokenThroughputMetrics":{"type":"object","properties":{"p50_tokens_per_second":{"type":["number","null"],"format":"double"},"p95_tokens_per_second":{"type":["number","null"],"format":"double"},"sample_count":{"type":"integer","format":"uint64","minimum":0}},"required":["sample_count"]},"ProviderAggregateMetrics":{"type":"object","properties":{"cache_hit_rate":{"type":"number","format":"double"},"latency":{"$ref":"#/$defs/ProviderLatencyMetrics"},"p50_latency_ms":{"description":"Request-weighted average of per-model p50 latencies. Not a true\ncross-bucket p50 (that would need a separate query), but cheap\nand close enough for a discovery panel.","type":"integer","format":"uint64","minimum":0},"request_count":{"type":"integer","format":"uint64","minimum":0},"success_rate":{"description":"Successful responses divided by (success + provider_error +\ntimeout). 0.0 when no scored requests fell in the window.","type":"number","format":"double"},"throughput":{"$ref":"#/$defs/ProviderThroughputMetrics"}},"required":["request_count","success_rate","p50_latency_ms","latency","throughput","cache_hit_rate"]},"ProviderCatalogEntry":{"description":"One provider as it appears to public discovery clients.","type":"object","properties":{"access":{"description":"How a caller obtains access to this provider — see [`Access`]. Only\n`api_key` providers accept a bring-your-own-key credential; the console\nfilters its BYOK page on `access == \"api_key\"`. (`local_oauth` /\n`local_pkce` providers are not in this catalog at all — the router\ncannot pool them — so in practice this is `api_key` or `private`.)","$ref":"#/$defs/Access"},"aggregate":{"$ref":"#/$defs/ProviderAggregateMetrics"},"byok":{"description":"`true` when a caller may bring their own key — derived alias of\n`access == \"api_key\"`, kept for back-compat with existing clients.\n`false` for the platform pool, which routes platform-only.","type":"boolean"},"community":{"description":"`true` for an unaffiliated community reseller; `false` (default) for\na first-party or official upstream.","type":"boolean"},"id":{"description":"Stable public handle: the provider's registry name.","type":"string"},"metadata":{"anyOf":[{"$ref":"#/$defs/ProviderMetadata"},{"type":"null"}]},"metrics_window_seconds":{"type":"integer","format":"uint64","minimum":0},"models":{"type":"array","items":{"$ref":"#/$defs/ProviderModelCatalogEntry"}},"name":{"description":"Human-readable provider name. Always present — providers are no\nlonger anonymized.","type":"string"},"rate_limit":{"$ref":"#/$defs/ProviderRateLimit"},"status":{"$ref":"#/$defs/ProviderStatus"}},"required":["id","name","community","access","byok","status","rate_limit","metrics_window_seconds","aggregate","models"]},"ProviderLatencyMetrics":{"type":"object","properties":{"first_token":{"$ref":"#/$defs/FirstTokenLatencyMetrics"}},"required":["first_token"]},"ProviderMetadata":{"description":"Public organization metadata for the provider responsible for a registry\n`api_base`. Optional policy/status links are descriptive only; routing does\nnot depend on them.","type":"object","properties":{"headquarters":{"description":"ISO 3166-1 alpha-2 country code for the provider organization's\nheadquarters.","type":"string"},"name":{"description":"Human-readable organization or product name.","type":"string"},"privacy_policy_url":{"type":["string","null"],"default":null},"slug":{"description":"Stable UI/API slug for the organization or product.","type":"string"},"status_page_url":{"type":["string","null"],"default":null},"terms_of_service_url":{"type":["string","null"],"default":null}},"required":["headquarters","name","slug"]},"ProviderModelCatalogEntry":{"type":"object","properties":{"hosted":{"description":"`true` when this model is in the hosted set (OSS `models.json`).\n`false` marks a BYOK/BYO-subscription extra, surfaced only on the\ncaller-scoped view when the caller has a key for this provider.","type":"boolean"},"id":{"description":"Canonical model id (e.g. `claude-sonnet-4-6`). The vendor's own\n`provider_model_id` is deliberately not exposed.","type":"string"},"metrics":{"$ref":"#/$defs/ProviderModelMetrics"},"pricing":{"$ref":"#/$defs/ModelPricing"}},"required":["id","hosted","pricing","metrics"]},"ProviderModelMetrics":{"type":"object","properties":{"latency":{"$ref":"#/$defs/ProviderLatencyMetrics"},"p50_latency_ms":{"type":"integer","format":"uint64","minimum":0},"request_count":{"type":"integer","format":"uint64","minimum":0},"success_rate":{"type":"number","format":"double"},"throughput":{"$ref":"#/$defs/ProviderThroughputMetrics"}},"required":["request_count","success_rate","p50_latency_ms","latency","throughput"]},"ProviderRateLimit":{"type":"object","properties":{"current_rpm":{"description":"In-process sliding-window admission count for this provider.","type":"integer","format":"uint32","minimum":0},"declared_rpm":{"description":"Provider-wide declared RPM from the wildcard `*` pattern in\n`rate_limits`. Omitted when the provider's YAML declares no\nwildcard entry — per-model overrides are intentionally not\nsurfaced, since the response shape is one rate per provider.","type":["integer","null"],"format":"uint32","minimum":0}},"required":["current_rpm"]},"ProviderStatus":{"description":"Provider lifecycle state.","type":"string","enum":["active","staging","suspended","withdrawn"]},"ProviderThroughputMetrics":{"type":"object","properties":{"output_tokens":{"$ref":"#/$defs/OutputTokenThroughputMetrics"}},"required":["output_tokens"]}}}}}}}}},"/v1/stats/usage":{"get":{"tags":["Discovery"],"summary":"Platform token usage statistics","description":"Aggregate token usage across the whole platform for a rolling window, bucketed by day and broken down by model. Public and unauthenticated — these are published figures, not per-account usage; for that see `GET /v1/namespaces/{nsid}/usage`.\n\nCounts only requests that succeeded. `completion_tokens` already includes `reasoning_tokens`, so `total_tokens` is `prompt_tokens + completion_tokens` — adding reasoning on top double-counts. Served from a 5-minute cache.","operationId":"getUsageStats","parameters":[{"in":"query","name":"days","description":"Window length in days, 1–90 (default 14). Out-of-range values are clamped.","schema":{"type":"string"},"style":"form"},{"in":"query","name":"top","description":"How many models to break out per day in `series` before the tail is folded into an `other` bucket, 1–25 (default 8). Does not truncate the `models` array.","schema":{"type":"string"},"style":"form"}],"responses":{"200":{"description":"Platform-wide token usage for the requested window.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"UsageStatsResponse","type":"object","properties":{"models":{"description":"Every model with traffic in the window, busiest first. Not truncated —\n`top` only controls the per-day `series` breakdown.","type":"array","items":{"$ref":"#/$defs/ModelUsage"}},"open_weight_token_share":{"description":"Share of `totals.total_tokens` served by open-weight models, over the\ntokens whose licensing is known. `null` when no such traffic exists in\nthe window — distinct from `0.0`, which means known-and-none.","type":["number","null"],"format":"double"},"series":{"type":"array","items":{"$ref":"#/$defs/UsageDay"}},"totals":{"$ref":"#/$defs/UsageTotals"},"window":{"$ref":"#/$defs/UsageWindow"}},"required":["window","totals","models","series"],"$defs":{"ModelUsage":{"type":"object","properties":{"completion_tokens":{"type":"integer","format":"int64"},"id":{"type":"string"},"open_weights":{"description":"Open-weight licensing from the registry; omitted when the model is not\na canonical declaration. Absent means unknown, never \"proprietary\".","type":["boolean","null"]},"prompt_tokens":{"type":"integer","format":"int64"},"request_count":{"type":"integer","format":"int64"},"token_share":{"description":"This model's share of `totals.total_tokens`, 0.0–1.0.","type":"number","format":"double"},"total_tokens":{"type":"integer","format":"int64"}},"required":["id","prompt_tokens","completion_tokens","total_tokens","request_count","token_share"]},"UsageDay":{"type":"object","properties":{"by_model":{"description":"Tokens per broken-out model for this day, plus an `other` key carrying\nthe folded tail. Models with no traffic on a given day are omitted\nrather than reported as zero.","type":"object","additionalProperties":{"type":"integer","format":"int64"}},"date":{"type":"string","format":"date"},"request_count":{"type":"integer","format":"int64"},"total_tokens":{"type":"integer","format":"int64"}},"required":["date","total_tokens","request_count","by_model"]},"UsageTotals":{"type":"object","properties":{"completion_tokens":{"description":"Total output tokens, inclusive of `reasoning_tokens`.","type":"integer","format":"int64"},"prompt_tokens":{"type":"integer","format":"int64"},"reasoning_tokens":{"description":"Subset of `completion_tokens`, reported for detail. Not additive.","type":"integer","format":"int64"},"request_count":{"type":"integer","format":"int64"},"total_tokens":{"description":"`prompt_tokens + completion_tokens`.","type":"integer","format":"int64"}},"required":["prompt_tokens","completion_tokens","reasoning_tokens","total_tokens","request_count"]},"UsageWindow":{"type":"object","properties":{"bucket":{"description":"Bucket granularity of `series`. Always `day` today.","type":"string"},"days":{"type":"integer","format":"uint16","maximum":65535,"minimum":0},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}},"required":["from","to","days","bucket"]}}}}}}}}},"/v1/byok/encryption-pubkey":{"get":{"tags":["BYOK"],"summary":"Get BYOK sealed-box public key","description":"Returns the node's current X25519 sealed-box public key plus its `kek_id` fingerprint. The console encrypts the user's provider key against this pubkey before storing the ciphertext — the node never sees plaintext on the write path.\n\nHonors `If-None-Match: \"<kek_id>\"` for cheap caching, returning `304 Not Modified` when the cached fingerprint still matches.","operationId":"getEncryptionPubkey","parameters":[{"in":"header","name":"If-None-Match","description":"Quoted `kek_id` from a prior response.","schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Current sealed-box public key.","headers":{"ETag":{"description":"Quoted `kek_id` of the returned key.","style":"simple","schema":{"type":"string"}},"Cache-Control":{"description":"`private, max-age=300` — encourages a 5-minute client cache.","style":"simple","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"EncryptionPubkeyResponse","description":"Response body for `GET /v1/byok/encryption-pubkey`. Carries the current\nsealed-box public key plus its fingerprint so the console can encrypt\nprovider keys against it.","type":"object","properties":{"kek_id":{"description":"Fingerprint of the current sealed-box keypair. Pin this when caching;\npass it back via `If-None-Match` to short-circuit on `304 Not Modified`.","type":"string"},"public_key":{"description":"Base64-encoded X25519 public key. Use it with libsodium's `crypto_box_seal`\n(or any sealed-box implementation) to encrypt provider keys client-side.","type":"string"}},"required":["kek_id","public_key"]}}}},"304":{"description":"Cached `kek_id` still matches — body is empty."}}}},"/metrics":{"get":{"tags":["Observability"],"summary":"Prometheus metrics scrape","description":"Returns Prometheus-format metrics for ingestion by a scraper. Not intended for human callers — point Prometheus, Grafana Agent, or any OpenMetrics-compatible collector at this endpoint.\n\nResponds `404 Not Found` when the node was built or configured without a metrics renderer; scrapers can use that as a feature probe.","operationId":"getMetrics","responses":{"200":{"description":"Prometheus-format metrics — counters, gauges, and histograms covering routing decisions, upstream latency, and credit settlement.","content":{"text/plain":{"schema":{"description":"Prometheus text-exposition format (version 0.0.4).","type":"string"}}}},"404":{"description":"Metrics renderer is not configured on this node — scrapers can use the 404 to probe whether `/metrics` is enabled."}}}},"/v1/namespaces":{"get":{"tags":["Management"],"summary":"List the caller's namespaces","description":"Every live namespace owned by the calling user, oldest first.\n\n_Requires the `namespace:read` scope._","operationId":"listNamespaces","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"post":{"tags":["Management"],"summary":"Create a namespace","description":"Creates a namespace owned by the caller. The name must be unique among the caller's live namespaces (409 on collision).\n\n_Requires the `namespace:write` scope._","operationId":"createNamespace","requestBody":{"description":"Request body. See the endpoint description for shape.","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}":{"delete":{"tags":["Management"],"summary":"Delete a namespace and cascade its resources","description":"Ownership-checked. Refuses the caller's last namespace (409). Destroys the namespace's keys, OAuth tokens/clients, and policies; archives the row; detaches usage history. The wallet and BYOK keys (user-keyed) are retained.\n\n_Requires the `namespace:write` scope._","operationId":"deleteNamespace","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/account":{"get":{"tags":["Management"],"summary":"Read the caller's user profile","description":"Returns id, email, display_name, created_at.\n\n_Requires the `user:read` scope._","operationId":"getAccount","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"delete":{"tags":["Management"],"summary":"Delete the caller's account","description":"Rust-first account deletion: destroys every credential under the user (API keys, OAuth tokens/clients, BYOK keys), archives all owned namespaces, and tombstones the IdP subject so the account cannot be re-provisioned. Irreversible; the caller's own session is revoked.\n\n_Requires the `user:write` scope._","operationId":"deleteAccount","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"patch":{"tags":["Management"],"summary":"Update the caller's profile","description":"Edits the one user-mutable field, `display_name`. `email` and the IdP identifier are read-only here.\n\n_Requires the `user:write` scope._","operationId":"updateAccount","requestBody":{"description":"Request body. See the endpoint description for shape.","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/access-codes/me":{"get":{"tags":["Management"],"summary":"Get the caller's current access code","description":"Returns the repository-configured policy bound to the caller, its validity status, and optional quota consumption. Returns 404 when the caller has no code binding.\n\n_Requires the `user:read` scope._","operationId":"getCurrentAccessCode","responses":{"200":{"description":"Current access code status.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"AccessCodeStatus","type":"object","properties":{"code":{"type":"string"},"ends_at":{"type":["string","null"],"format":"date-time"},"policy_id":{"type":"string"},"quota":{"anyOf":[{"$ref":"#/$defs/AccessCodeQuotaStatus"},{"type":"null"}]},"starts_at":{"type":["string","null"],"format":"date-time"},"status":{"type":"string"}},"required":["policy_id","code","status"],"$defs":{"AccessCodeQuotaStatus":{"type":"object","properties":{"consumed":{"type":"integer","format":"int64"},"limit":{"type":"integer","format":"int64"},"unit":{"type":"string"}},"required":["unit","limit","consumed"]}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/access-codes/claim":{"post":{"tags":["Management"],"summary":"Claim an access code","description":"Claims an active code-filtered Access Policy. Re-claiming the same code is idempotent; claiming a different code while the current policy is active returns 409. Unknown or inactive codes return 404.\n\n_Requires the `user:write` scope._","operationId":"claimAccessCode","requestBody":{"description":"Access code claim request.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ClaimAccessCodeRequest","type":"object","properties":{"code":{"type":"string"}},"required":["code"]}}},"required":true},"responses":{"200":{"description":"Claimed access code status.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"AccessCodeStatus","type":"object","properties":{"code":{"type":"string"},"ends_at":{"type":["string","null"],"format":"date-time"},"policy_id":{"type":"string"},"quota":{"anyOf":[{"$ref":"#/$defs/AccessCodeQuotaStatus"},{"type":"null"}]},"starts_at":{"type":["string","null"],"format":"date-time"},"status":{"type":"string"}},"required":["policy_id","code","status"],"$defs":{"AccessCodeQuotaStatus":{"type":"object","properties":{"consumed":{"type":"integer","format":"int64"},"limit":{"type":"integer","format":"int64"},"unit":{"type":"string"}},"required":["unit","limit","consumed"]}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/requests/{request_id}/settlement":{"get":{"tags":["Management"],"summary":"Get settlement for one invoked request","description":"Returns only a request owned by the exact invoking credential. A request owned by another key is indistinguishable from an absent request (404). The response contains content-free usage, authoritative calculation/collection states, and the complete versioned immutable billing audit when present; it never includes prompt, response, or credential material.\n\n_Requires the `inference:invoke` scope._","operationId":"getRequestSettlement","parameters":[{"in":"path","name":"request_id","description":"Stable request id returned by the inference API.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Request-scoped settlement receipt.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"RequestSettlementResponseDoc","description":"Request-scoped settlement receipt returned to the inference credential\nthat invoked the request. No prompt or response payload is exposed.","type":"object","properties":{"billing_audit":{"$ref":"#/$defs/NullableDoc4"},"billing_collection_status":{"$ref":"#/$defs/BillingCollectionStatusDoc"},"billing_fallbacks":{"$ref":"#/$defs/NullableDoc3"},"billing_status":{"$ref":"#/$defs/BillingStatusProjectionDoc"},"final_charge_micro_usd":{"$ref":"#/$defs/NullableDoc2"},"model_id":{"$ref":"#/$defs/NullableDoc"},"provider_id":{"$ref":"#/$defs/NullableDoc"},"request_id":{"type":"string"},"state":{"description":"One of `pending`, `settlement_missing`, `computed`, `not_charged`, or\n`unknown`.","$ref":"#/$defs/RequestSettlementStateDoc"},"usage":{"$ref":"#/$defs/RequestSettlementUsageDoc"}},"required":["request_id","state","model_id","provider_id","usage","final_charge_micro_usd","billing_status","billing_fallbacks","billing_collection_status","billing_audit"],"$defs":{"BillingBillableUsageDoc":{"type":"object","properties":{"input_cache_read_tokens":{"type":"integer","format":"uint64","minimum":0},"input_cache_write_tokens":{"type":"integer","format":"uint64","minimum":0},"input_no_cache_tokens":{"type":"integer","format":"uint64","minimum":0},"output_reasoning_tokens":{"type":"integer","format":"uint64","minimum":0},"output_text_tokens":{"type":"integer","format":"uint64","minimum":0}},"required":["input_no_cache_tokens","input_cache_read_tokens","input_cache_write_tokens","output_text_tokens","output_reasoning_tokens"]},"BillingChargeBucketDoc":{"type":"string","enum":["input_no_cache","input_cache_read","input_cache_write","output_text","output_reasoning"]},"BillingChargeLineDoc":{"type":"object","properties":{"billable_tokens":{"type":"integer","format":"uint64","minimum":0},"bucket":{"$ref":"#/$defs/BillingChargeBucketDoc"},"normalized_rate_micro_usd_per_million":{"$ref":"#/$defs/BillingIntegerDoc"},"scaled_numerator":{"$ref":"#/$defs/BillingIntegerDoc"}},"required":["bucket","billable_tokens","normalized_rate_micro_usd_per_million","scaled_numerator"]},"BillingCollectionStatusDoc":{"type":"string","enum":["pending","prepared","booked","applied","manual_review","not_applicable","collection_missing","manual_reconciliation","legacy_unknown"]},"BillingContextTierSnapshotDoc":{"type":"object","properties":{"above_input_tokens":{"type":"integer","format":"uint64","minimum":0},"rates":{"$ref":"#/$defs/BillingPricingRatesSnapshotDoc"}},"required":["above_input_tokens","rates"]},"BillingDecisionDoc":{"type":"object","properties":{"billable_usage":{"$ref":"#/$defs/BillingBillableUsageDoc"},"calculator_version":{"type":"string"},"charge_breakdown":{"type":"array","items":{"$ref":"#/$defs/BillingChargeLineDoc"}},"collection_required":{"type":"boolean"},"discount_snapshot":{"$ref":"#/$defs/NullableDoc13"},"fallbacks":{"type":"array","items":{"$ref":"#/$defs/BillingFallbackDoc"}},"final_charge_micro_usd":{"$ref":"#/$defs/NullableDoc2"},"normalized_pricing":{"$ref":"#/$defs/BillingNormalizedPricingDoc"},"pre_discount_charge_micro_usd":{"$ref":"#/$defs/NullableDoc2"},"reported_usage":{"$ref":"#/$defs/BillingReportedUsageDoc"},"request_succeeded":{"description":"Immutable success/failure input used by the versioned calculator.","type":"boolean"},"status":{"$ref":"#/$defs/BillingStatusDoc"},"usage_capped":{"type":"boolean"},"usage_evidence":{"$ref":"#/$defs/BillingUsageEvidenceDoc"}},"required":["status","request_succeeded","calculator_version","reported_usage","usage_evidence","billable_usage","normalized_pricing","charge_breakdown","fallbacks","usage_capped","discount_snapshot","pre_discount_charge_micro_usd","final_charge_micro_usd","collection_required"]},"BillingDiscountSnapshotDoc":{"type":"object","properties":{"factor_bps":{"type":"integer","format":"uint16","maximum":65535,"minimum":0},"input_charge_micro_usd":{"$ref":"#/$defs/NullableDoc2"},"output_charge_micro_usd":{"$ref":"#/$defs/NullableDoc2"},"source":{"$ref":"#/$defs/BillingDiscountSourceDoc"}},"required":["source","factor_bps","input_charge_micro_usd","output_charge_micro_usd"]},"BillingDiscountSourceDoc":{"type":"string","enum":["policy_v2","legacy_promotion"]},"BillingFallbackDoc":{"type":"string","enum":["cache_read_to_no_cache","cache_write_to_no_cache","reasoning_to_text"]},"BillingIntegerDoc":{"description":"The calculator serializes i128 evidence as a JSON integer while it fits a\nJSON integer branch and as a decimal string outside the u64 range.","anyOf":[{"type":"integer","format":"int64"},{"type":"integer","format":"uint64","minimum":0},{"type":"string"}]},"BillingNormalizedPricingDoc":{"type":"object","properties":{"input_cache_read":{"$ref":"#/$defs/NullableDoc11"},"input_cache_write":{"$ref":"#/$defs/NullableDoc11"},"input_no_cache":{"$ref":"#/$defs/NullableDoc11"},"output_audio":{"$ref":"#/$defs/NullableDoc11"},"output_image":{"$ref":"#/$defs/NullableDoc11"},"output_reasoning":{"$ref":"#/$defs/NullableDoc11"},"output_text":{"$ref":"#/$defs/NullableDoc11"}},"required":["input_no_cache","input_cache_read","input_cache_write","output_text","output_reasoning","output_image","output_audio"]},"BillingNormalizedRateDoc":{"type":"object","properties":{"micro_usd_per_million":{"$ref":"#/$defs/NullableDoc12"},"source_usd_per_million":{"type":"string"}},"required":["source_usd_per_million","micro_usd_per_million"]},"BillingPricingRatesSnapshotDoc":{"type":"object","properties":{"input_cache_read":{"$ref":"#/$defs/NullableDoc"},"input_cache_write":{"$ref":"#/$defs/NullableDoc"},"input_no_cache":{"$ref":"#/$defs/NullableDoc"},"output_audio":{"$ref":"#/$defs/NullableDoc"},"output_image":{"$ref":"#/$defs/NullableDoc"},"output_reasoning":{"$ref":"#/$defs/NullableDoc"},"output_text":{"$ref":"#/$defs/NullableDoc"}},"required":["input_no_cache","input_cache_read","input_cache_write","output_text","output_reasoning","output_image","output_audio"]},"BillingPricingSnapshotDoc":{"type":"object","properties":{"base":{"$ref":"#/$defs/BillingPricingRatesSnapshotDoc"},"context_tiers":{"type":"array","items":{"$ref":"#/$defs/BillingContextTierSnapshotDoc"}}},"required":["base","context_tiers"]},"BillingProviderUsageDoc":{"type":"object","properties":{"cache_read_tokens":{"type":"integer","format":"uint64","minimum":0},"cache_write_tokens":{"type":"integer","format":"uint64","minimum":0},"completion_tokens":{"type":"integer","format":"uint64","minimum":0},"prompt_tokens":{"type":"integer","format":"uint64","minimum":0},"reasoning_tokens":{"type":"integer","format":"uint64","minimum":0},"web_search_count":{"type":"integer","format":"uint64","minimum":0}},"required":["prompt_tokens","completion_tokens","reasoning_tokens","cache_read_tokens","cache_write_tokens","web_search_count"]},"BillingRawUsageFrameDoc":{"type":"object","properties":{"account_label":{"$ref":"#/$defs/NullableDoc"},"attempt_ordinal":{"type":"integer","format":"uint64","minimum":0},"frame_kind":{"$ref":"#/$defs/BillingRawUsageFrameKindDoc"},"frame_ordinal":{"type":"integer","format":"uint64","minimum":0},"provider_id":{"type":"string"},"provider_model_id":{"type":"string"},"usage":{"$ref":"#/$defs/BillingProviderUsageDoc"}},"required":["attempt_ordinal","frame_ordinal","frame_kind","provider_id","provider_model_id","account_label","usage"]},"BillingRawUsageFrameKindDoc":{"type":"string","enum":["usage","response_completed"]},"BillingRegistrySnapshotDoc":{"type":"object","properties":{"content_sha256":{"type":"string"},"loaded_at":{"type":"string","format":"date-time"},"source_ref":{"type":"string"}},"required":["source_ref","content_sha256","loaded_at"]},"BillingReportedUsageDoc":{"type":"object","properties":{"cache_read_tokens":{"type":"integer","format":"uint64","minimum":0},"cache_write_tokens":{"type":"integer","format":"uint64","minimum":0},"completion_tokens":{"type":"integer","format":"uint64","minimum":0},"media_input_count":{"type":"integer","format":"uint64","minimum":0},"media_output_count":{"type":"integer","format":"uint64","minimum":0},"prompt_tokens":{"type":"integer","format":"uint64","minimum":0},"reasoning_tokens":{"type":"integer","format":"uint64","minimum":0},"web_search_count":{"type":"integer","format":"uint64","minimum":0}},"required":["prompt_tokens","cache_read_tokens","cache_write_tokens","completion_tokens","reasoning_tokens","web_search_count","media_input_count","media_output_count"]},"BillingRouteSnapshotDoc":{"type":"object","properties":{"account_label":{"$ref":"#/$defs/NullableDoc"},"byok_used":{"type":"boolean"},"canonical_model_id":{"type":"string"},"pricing":{"$ref":"#/$defs/BillingPricingSnapshotDoc"},"provider_id":{"type":"string"},"provider_model_id":{"type":"string"},"registry":{"$ref":"#/$defs/BillingRegistrySnapshotDoc"}},"required":["provider_id","provider_model_id","account_label","canonical_model_id","pricing","registry","byok_used"]},"BillingStatusDoc":{"type":"string","enum":["computed","computed_with_fallback","computed_zero","byok","pricing_unavailable","invalid_pricing","invalid_usage","arithmetic_overflow","failed_not_charged"]},"BillingStatusProjectionDoc":{"description":"Read-time billing projection. `legacy_inconsistent` identifies a legacy\nterminal failed/cancelled/rejected request that conflicts with a persisted\nnumeric charge; the amount is withheld. It is not an immutable billing\ndecision status.","type":"string","enum":["computed","computed_with_fallback","computed_zero","byok","pricing_unavailable","invalid_pricing","invalid_usage","arithmetic_overflow","failed_not_charged","settlement_missing","legacy_computed","legacy_inconsistent","legacy_unknown","legacy_not_charged"]},"BillingUsageEstimatorSnapshotDoc":{"type":"object","properties":{"chars_per_token":{"type":"integer","format":"uint64","minimum":0},"version":{"description":"Immutable internal estimator identifier: 1–256 ASCII bytes matching\n`[A-Za-z0-9][A-Za-z0-9._:/-]*`.","type":"string"}},"required":["version","chars_per_token"]},"BillingUsageEvidenceDoc":{"type":"object","properties":{"effective_usage":{"$ref":"#/$defs/NullableDoc9"},"estimator":{"$ref":"#/$defs/NullableDoc10"},"raw_usage":{"$ref":"#/$defs/NullableDoc8"},"raw_usage_frames":{"type":"array","items":{"$ref":"#/$defs/BillingRawUsageFrameDoc"}},"source":{"$ref":"#/$defs/BillingUsageSourceDoc"}},"required":["source","raw_usage","raw_usage_frames","effective_usage","estimator"]},"BillingUsageSourceDoc":{"type":"string","enum":["provider_reported","provider_reported_deduplicated","provider_reported_conservative","estimated","absent","unverified_missing","unverified_duplicate","unverified_counter_mismatch","unverified_malformed"]},"NullableDoc":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","type":["string","null"]},"NullableDoc10":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","anyOf":[{"$ref":"#/$defs/BillingUsageEstimatorSnapshotDoc"},{"type":"null"}]},"NullableDoc11":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","anyOf":[{"$ref":"#/$defs/BillingNormalizedRateDoc"},{"type":"null"}]},"NullableDoc12":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","anyOf":[{"$ref":"#/$defs/BillingIntegerDoc"},{"type":"null"}]},"NullableDoc13":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","anyOf":[{"$ref":"#/$defs/BillingDiscountSnapshotDoc"},{"type":"null"}]},"NullableDoc2":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","type":["integer","null"],"format":"int64"},"NullableDoc3":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","type":["array","null"],"items":{"$ref":"#/$defs/BillingFallbackDoc"}},"NullableDoc4":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","anyOf":[{"$ref":"#/$defs/RequestBillingAuditDoc"},{"type":"null"}]},"NullableDoc5":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","type":["array","null"],"items":{"$ref":"#/$defs/BillingRouteSnapshotDoc"}},"NullableDoc6":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","anyOf":[{"$ref":"#/$defs/BillingRegistrySnapshotDoc"},{"type":"null"}]},"NullableDoc7":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","anyOf":[{"$ref":"#/$defs/BillingPricingSnapshotDoc"},{"type":"null"}]},"NullableDoc8":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","anyOf":[{"$ref":"#/$defs/BillingProviderUsageDoc"},{"type":"null"}]},"NullableDoc9":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","anyOf":[{"$ref":"#/$defs/BillingReportedUsageDoc"},{"type":"null"}]},"RequestBillingAuditDoc":{"type":"object","properties":{"attempted_route_snapshots":{"$ref":"#/$defs/NullableDoc5"},"audit_envelope_canonical_base64":{"description":"Exact canonical UTF-8 envelope bytes encoded with the RFC 4648 standard Base64 alphabet with padding.\nDecode this field, compute SHA-256 over the decoded bytes, and compare\nit with `audit_envelope_sha256`; then parse the decoded UTF-8 JSON and\ncompare its values with the public audit fields according to the\ndocumented `hash_version` mapping. This avoids language-specific JSON\nescaping or integer-formatting differences during strict verification.","type":"string"},"audit_envelope_sha256":{"description":"SHA-256 of a canonical object reconstructed from this response. The\ncanonical object contains exactly: `hash_version` set to `audit_hash_version`,\n`request_id`, `audit_schema_version`, `decision`,\n`selected_provider_id`, `selected_canonical_model_id`,\n`selected_provider_model_id`, `selected_account_label`,\n`attempted_route_snapshots`, `registry_snapshot`, `source_pricing`, and\n`selected_pricing`. Canonicalization emits compact JSON with\nrecursively sorted object keys. Null values are retained; array order is preserved.\nSHA-256 hashes the resulting UTF-8 JSON bytes. The public\n`audit_envelope_sha256`, `audit_envelope_canonical_base64`, and\n`created_at` are omitted.","type":"string"},"audit_hash_version":{"description":"Row-owned canonical audit-envelope hash contract used by\n`audit_envelope_sha256`. This value is persisted with the audit and is\nnever inferred from the server's current/default hash version.","type":"string"},"audit_schema_version":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"decision":{"$ref":"#/$defs/BillingDecisionDoc"},"registry_snapshot":{"$ref":"#/$defs/NullableDoc6"},"request_id":{"type":"string"},"selected_account_label":{"$ref":"#/$defs/NullableDoc"},"selected_canonical_model_id":{"$ref":"#/$defs/NullableDoc"},"selected_pricing":{"$ref":"#/$defs/NullableDoc7"},"selected_provider_id":{"$ref":"#/$defs/NullableDoc"},"selected_provider_model_id":{"$ref":"#/$defs/NullableDoc"},"source_pricing":{"$ref":"#/$defs/NullableDoc7"}},"required":["request_id","audit_schema_version","audit_hash_version","audit_envelope_sha256","audit_envelope_canonical_base64","created_at","selected_provider_id","selected_canonical_model_id","selected_provider_model_id","selected_account_label","attempted_route_snapshots","registry_snapshot","source_pricing","selected_pricing","decision"]},"RequestSettlementStateDoc":{"type":"string","enum":["pending","settlement_missing","computed","not_charged","unknown"]},"RequestSettlementUsageDoc":{"type":"object","properties":{"cache_read_tokens":{"type":"integer","format":"int64"},"cache_write_tokens":{"type":"integer","format":"int64"},"output_tokens":{"type":"integer","format":"int64"},"reasoning_tokens":{"type":"integer","format":"int64"},"uncached_input_tokens":{"type":"integer","format":"int64"}},"required":["uncached_input_tokens","cache_read_tokens","cache_write_tokens","output_tokens","reasoning_tokens"]}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/billing/balance":{"get":{"tags":["Management"],"summary":"Credit account balance","description":"Returns the raw balance, pending debits, and effective available amount in micro-USD.\n\n_Requires the `billing:read` scope._","operationId":"getBillingBalance","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/billing/transactions":{"get":{"tags":["Management"],"summary":"Paginated credit ledger history","description":"Credit ledger entries (topups, usage debits, refunds), newest first. `amount_micro_usd` is signed: positive for credits, negative for debits.\n\n_Requires the `billing:read` scope._","operationId":"listBillingTransactions","parameters":[{"in":"query","name":"limit","description":"Page size. Default 25, max 100.","schema":{"type":"string"},"style":"form"},{"in":"query","name":"offset","description":"Offset within the newest-first listing.","schema":{"type":"string"},"style":"form"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/billing/checkout/sessions":{"post":{"tags":["Management"],"summary":"Create a Stripe Checkout Session","description":"Creates a Stripe Checkout Session to buy credits. Returns the hosted URL the user must visit to complete payment.\n\n_Requires the `billing:write` scope._","operationId":"createCheckoutSession","requestBody":{"description":"Request body. See the endpoint description for shape.","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/billing/checkout/sessions/{session_id}/status":{"get":{"tags":["Management"],"summary":"Terminal status of a Checkout Session","description":"Returns the caller's Checkout Session status: `processing`, `succeeded`, `failed`, or `expired`. 404 if the session is not the caller's.\n\n_Requires the `billing:read` scope._","operationId":"getCheckoutSessionStatus","parameters":[{"in":"path","name":"session_id","description":"Stripe Checkout Session id.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/byok/keys":{"get":{"tags":["Management"],"summary":"List BYOK provider keys","description":"Metadata-only — never returns the sealed ciphertext.\n\n_Requires the `byok:read` scope._","operationId":"listByokKeys","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"post":{"tags":["Management"],"summary":"Upsert a BYOK provider key","description":"Stores a sealed-box ciphertext for one provider. Refuses any payload sealed against a `kek_id` other than the cloud's current encryption pubkey (`/v1/byok/encryption-pubkey`).\n\n_Requires the `byok:write` scope._","operationId":"upsertByokKey","requestBody":{"description":"Request body. See the endpoint description for shape.","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/byok/keys/{provider}":{"delete":{"tags":["Management"],"summary":"Delete a BYOK provider key","description":"\n\n_Requires the `byok:write` scope._","operationId":"deleteByokKey","parameters":[{"in":"path","name":"provider","description":"Provider name as registered in the cloud's provider catalog.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/keys":{"get":{"tags":["Management"],"summary":"List API keys for the calling account","description":"Account-scoped list of brk_ API keys. Never returns the secret.\n\n_Requires the `keys:read` scope._","operationId":"listApiKeys","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"post":{"tags":["Management"],"summary":"Mint a new API key","description":"Mint a brk_ API key. Returns the plaintext token exactly once.\n\nThe requested `scopes` must be a subset of the caller's effective scopes — no upscaling (RFC 6749 §3.3).\n\n_Requires the `keys:write` scope._","operationId":"mintApiKey","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"}],"requestBody":{"description":"Request body. See the endpoint description for shape.","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/keys/{id}":{"delete":{"tags":["Management"],"summary":"Revoke an API key","description":"Stamps `revoked_at` on the row. Subsequent verifies fail with 401.\n\n_Requires the `keys:write` scope._","operationId":"revokeApiKey","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the api_keys row.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/usage":{"get":{"tags":["Management"],"summary":"Aggregate spend / tokens for a window","description":"Uses immutable billing-audit charges when present and legacy request charges only when no audit exists. Billing anomaly counts keep null charges visible. Defaults to the last 30 days.\n\n_Requires the `usage:read` scope._","operationId":"getUsageAggregate","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"query","name":"from","description":"Inclusive RFC 3339 timestamp lower bound.","schema":{"type":"string"},"style":"form"},{"in":"query","name":"to","description":"Exclusive RFC 3339 timestamp upper bound.","schema":{"type":"string"},"style":"form"}],"responses":{"200":{"description":"Namespace billing and token aggregate.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"UsageResponseDoc","type":"object","properties":{"capability_request_counts":{"type":"object","additionalProperties":{"type":"integer","format":"int64"}},"completion_tokens":{"type":"integer","format":"int64"},"from":{"type":"string","format":"date-time"},"prompt_tokens":{"type":"integer","format":"int64"},"request_count":{"type":"integer","format":"int64"},"spend_micro_usd":{"type":"integer","format":"int64"},"to":{"type":"string","format":"date-time"}},"required":["from","to","spend_micro_usd","prompt_tokens","completion_tokens","request_count","capability_request_counts"]}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/requests":{"get":{"tags":["Management"],"summary":"Paginated request history","description":"Per-request metadata. Never includes the prompt or response body.\n\n_Requires the `usage:read` scope._","operationId":"listRequests","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"query","name":"limit","description":"Page size. Default 25, max 100.","schema":{"type":"string"},"style":"form"},{"in":"query","name":"offset","description":"Offset within the newest-first listing.","schema":{"type":"string"},"style":"form"}],"responses":{"200":{"description":"Paginated request history.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"RequestsResponseDoc","description":"Management request-history page returned by\n`/v1/namespaces/{nsid}/requests`.","type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/$defs/RequestEnvelopeDoc"}},"limit":{"type":"integer","format":"uint64","minimum":0},"offset":{"type":"integer","format":"uint64","minimum":0}},"required":["data","limit","offset"],"$defs":{"BillingProviderUsageDoc":{"type":"object","properties":{"cache_read_tokens":{"type":"integer","format":"uint64","minimum":0},"cache_write_tokens":{"type":"integer","format":"uint64","minimum":0},"completion_tokens":{"type":"integer","format":"uint64","minimum":0},"prompt_tokens":{"type":"integer","format":"uint64","minimum":0},"reasoning_tokens":{"type":"integer","format":"uint64","minimum":0},"web_search_count":{"type":"integer","format":"uint64","minimum":0}},"required":["prompt_tokens","completion_tokens","reasoning_tokens","cache_read_tokens","cache_write_tokens","web_search_count"]},"BillingRawUsageFrameDoc":{"type":"object","properties":{"account_label":{"$ref":"#/$defs/NullableDoc"},"attempt_ordinal":{"type":"integer","format":"uint64","minimum":0},"frame_kind":{"$ref":"#/$defs/BillingRawUsageFrameKindDoc"},"frame_ordinal":{"type":"integer","format":"uint64","minimum":0},"provider_id":{"type":"string"},"provider_model_id":{"type":"string"},"usage":{"$ref":"#/$defs/BillingProviderUsageDoc"}},"required":["attempt_ordinal","frame_ordinal","frame_kind","provider_id","provider_model_id","account_label","usage"]},"BillingRawUsageFrameKindDoc":{"type":"string","enum":["usage","response_completed"]},"BillingReportedUsageDoc":{"type":"object","properties":{"cache_read_tokens":{"type":"integer","format":"uint64","minimum":0},"cache_write_tokens":{"type":"integer","format":"uint64","minimum":0},"completion_tokens":{"type":"integer","format":"uint64","minimum":0},"media_input_count":{"type":"integer","format":"uint64","minimum":0},"media_output_count":{"type":"integer","format":"uint64","minimum":0},"prompt_tokens":{"type":"integer","format":"uint64","minimum":0},"reasoning_tokens":{"type":"integer","format":"uint64","minimum":0},"web_search_count":{"type":"integer","format":"uint64","minimum":0}},"required":["prompt_tokens","cache_read_tokens","cache_write_tokens","completion_tokens","reasoning_tokens","web_search_count","media_input_count","media_output_count"]},"BillingStatusProjectionDoc":{"description":"Read-time billing projection. `legacy_inconsistent` identifies a legacy\nterminal failed/cancelled/rejected request that conflicts with a persisted\nnumeric charge; the amount is withheld. It is not an immutable billing\ndecision status.","type":"string","enum":["computed","computed_with_fallback","computed_zero","byok","pricing_unavailable","invalid_pricing","invalid_usage","arithmetic_overflow","failed_not_charged","settlement_missing","legacy_computed","legacy_inconsistent","legacy_unknown","legacy_not_charged"]},"BillingUsageEstimatorSnapshotDoc":{"type":"object","properties":{"chars_per_token":{"type":"integer","format":"uint64","minimum":0},"version":{"description":"Immutable internal estimator identifier: 1–256 ASCII bytes matching\n`[A-Za-z0-9][A-Za-z0-9._:/-]*`.","type":"string"}},"required":["version","chars_per_token"]},"BillingUsageEvidenceDoc":{"type":"object","properties":{"effective_usage":{"$ref":"#/$defs/NullableDoc5"},"estimator":{"$ref":"#/$defs/NullableDoc6"},"raw_usage":{"$ref":"#/$defs/NullableDoc4"},"raw_usage_frames":{"type":"array","items":{"$ref":"#/$defs/BillingRawUsageFrameDoc"}},"source":{"$ref":"#/$defs/BillingUsageSourceDoc"}},"required":["source","raw_usage","raw_usage_frames","effective_usage","estimator"]},"BillingUsageSourceDoc":{"type":"string","enum":["provider_reported","provider_reported_deduplicated","provider_reported_conservative","estimated","absent","unverified_missing","unverified_duplicate","unverified_counter_mismatch","unverified_malformed"]},"NullableDoc":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","type":["string","null"]},"NullableDoc2":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","type":["integer","null"],"format":"int32"},"NullableDoc3":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","type":["integer","null"],"format":"int64"},"NullableDoc4":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","anyOf":[{"$ref":"#/$defs/BillingProviderUsageDoc"},{"type":"null"}]},"NullableDoc5":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","anyOf":[{"$ref":"#/$defs/BillingReportedUsageDoc"},{"type":"null"}]},"NullableDoc6":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","anyOf":[{"$ref":"#/$defs/BillingUsageEstimatorSnapshotDoc"},{"type":"null"}]},"NullableDoc7":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","type":["boolean","null"]},"NullableDoc8":{"description":"A JSON field that is always present on the wire but may contain `null`.\nUsing `Option<T>` directly makes schemars mark the property optional;\n`#[schemars(required)]` makes it non-nullable. This transparent wrapper\nmodels the actual serde behavior: required + nullable.","type":["string","null"],"format":"date-time"},"RequestEnvelopeDoc":{"type":"object","properties":{"billing_status":{"$ref":"#/$defs/BillingStatusProjectionDoc"},"completed_at":{"$ref":"#/$defs/NullableDoc8"},"completion_tokens":{"type":"integer","format":"int64"},"created_at":{"type":"string","format":"date-time"},"final_charge_micro_usd":{"$ref":"#/$defs/NullableDoc3"},"finish_reason":{"$ref":"#/$defs/NullableDoc"},"first_token_kind":{"description":"`reasoning`, `text`, or `tool` when TTFT is available.","$ref":"#/$defs/NullableDoc"},"funding_source":{"$ref":"#/$defs/NullableDoc"},"generation_duration_ms":{"description":"First-to-last semantic stream delta duration in milliseconds.","$ref":"#/$defs/NullableDoc3"},"id":{"type":"string"},"model_id":{"$ref":"#/$defs/NullableDoc"},"prompt_tokens":{"type":"integer","format":"int64"},"provider_id":{"$ref":"#/$defs/NullableDoc"},"request_duration_ms":{"description":"Total request lifecycle duration in milliseconds.","$ref":"#/$defs/NullableDoc3"},"request_id":{"type":"string"},"routing_profile":{"$ref":"#/$defs/NullableDoc"},"status":{"type":"string"},"status_code":{"$ref":"#/$defs/NullableDoc2"},"streamed":{"$ref":"#/$defs/NullableDoc7"},"ttft_ms":{"description":"Successful provider attempt to first semantic stream delta, in ms.","$ref":"#/$defs/NullableDoc3"},"upstream_duration_ms":{"description":"Duration of the final provider-facing operation in milliseconds.","$ref":"#/$defs/NullableDoc3"},"usage_evidence":{"description":"Omitted for legacy requests that have no immutable billing audit.","anyOf":[{"$ref":"#/$defs/BillingUsageEvidenceDoc"},{"type":"null"}]},"used_capabilities":{"type":"array","items":{"type":"string"}}},"required":["id","request_id","status","finish_reason","status_code","model_id","provider_id","prompt_tokens","completion_tokens","final_charge_micro_usd","billing_status","funding_source","streamed","request_duration_ms","upstream_duration_ms","ttft_ms","first_token_kind","generation_duration_ms","created_at","completed_at","routing_profile","used_capabilities"]}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/policies":{"get":{"tags":["Management"],"summary":"List account policies","description":"\n\n_Requires the `policy:read` scope._","operationId":"listPolicies","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"query","name":"kind","description":"Optional filter — `budget`, `rate_limit`, `guardrail`, or `preset`. Unknown values return 400.","schema":{"type":"string"},"style":"form"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"post":{"tags":["Management"],"summary":"Create a policy","description":"Create a `budget` / `rate_limit` / `guardrail` / `preset` policy. The `spec` body must match the requested `kind`.\n\n_Requires the `policy:write` scope._","operationId":"createPolicy","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"}],"requestBody":{"description":"Request body. See the endpoint description for shape.","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/policies/effective":{"get":{"tags":["Management"],"summary":"Preview the engine's effective policy for a principal","description":"Returns the engine's combined view (budgets, rate_limits, guardrail) without making a real inference request. The queried principal must belong to the caller's account.\n\n_Requires the `policy:read` scope._","operationId":"getEffectivePolicy","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"query","name":"principal_type","description":"One of `namespace`, `api_key`, `oauth_token`, `oauth_client`.","schema":{"type":"string"},"style":"form"},{"in":"query","name":"principal_id","description":"Id of the principal. Must belong to the caller's account or 404.","schema":{"type":"string"},"style":"form"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/policies/{id}":{"get":{"tags":["Management"],"summary":"Read a single policy by id","description":"Returns the policy if it exists and belongs to the caller's account; 404 otherwise (no cross-tenant existence leak).\n\n_Requires the `policy:read` scope._","operationId":"getPolicy","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the `policies` row.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"put":{"tags":["Management"],"summary":"Update a policy's name or spec","description":"In-place update of a policy's `name` and / or `spec`. Kind changes are not supported — recreate the policy if the kind needs to differ.\n\n_Requires the `policy:write` scope._","operationId":"updatePolicy","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"}],"requestBody":{"description":"Request body. See the endpoint description for shape.","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"delete":{"tags":["Management"],"summary":"Delete a policy and its bindings","description":"\n\n_Requires the `policy:write` scope._","operationId":"deletePolicy","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the `policies` row.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/policies/{id}/bind":{"post":{"tags":["Management"],"summary":"Bind a policy to a principal","description":"Attaches the policy to a principal (account / api_key / oauth_token / oauth_client). The engine sums all bindings most-restrictive-wins at request time.\n\n_Requires the `policy:write` scope._","operationId":"bindPolicy","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"}],"requestBody":{"description":"Request body. See the endpoint description for shape.","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/policies/{id}/bind/{binding_id}":{"delete":{"tags":["Management"],"summary":"Remove a policy binding","description":"\n\n_Requires the `policy:write` scope._","operationId":"unbindPolicy","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the policy.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"binding_id","description":"Surrogate id of the binding row.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/policies/{id}/disable":{"post":{"tags":["Management"],"summary":"Park a policy without deleting it","description":"Stamps `disabled_at = now()`. The engine skips disabled rows when computing effective policy; the management surface still surfaces them so an operator can re-enable. Idempotent — re-disabling returns 200.\n\n_Requires the `policy:write` scope._","operationId":"disablePolicy","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the `policies` row.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/policies/{id}/enable":{"post":{"tags":["Management"],"summary":"Re-enable a previously disabled policy","description":"Clears `disabled_at`. The engine starts honouring the row again on the next request. Idempotent.\n\n_Requires the `policy:write` scope._","operationId":"enablePolicy","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the `policies` row.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/policies/{id}/bindings":{"get":{"tags":["Management"],"summary":"List bindings attached to one policy","description":"Returns every binding referencing the policy. The policy must belong to the caller's account or 404 is returned.\n\n_Requires the `policy:read` scope._","operationId":"listPolicyBindings","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the `policies` row.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/principals/{principal_type}/{principal_id}/policies":{"get":{"tags":["Management"],"summary":"List policies bound to a principal","description":"Returns every policy directly bound to the named principal. The principal must belong to the caller's account — mismatch returns 404 (no cross-tenant enumeration).\n\n_Requires the `policy:read` scope._","operationId":"listPrincipalPolicies","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"principal_type","description":"One of `namespace`, `api_key`, `oauth_token`, `oauth_client`.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"principal_id","description":"Id of the principal. Must belong to the caller's account or 404.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/budgets":{"get":{"tags":["Management"],"summary":"List the account's budget policies","description":"Typed list of `kind = 'budget'` rows. Same storage as `/v1/policies?kind=budget` but the response carries flat budget objects instead of `{ kind, spec }` envelopes.\n\n_Requires the `policy:read` scope._","operationId":"listBudgets","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Budget list.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"BudgetListResponse","type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/$defs/BudgetEnvelope"}}},"required":["data"],"$defs":{"BudgetEnvelope":{"description":"One budget as it appears on the wire. The shape is flat — no\n`kind`/`spec` envelope — because this endpoint only ever produces\nbudgets.","type":"object","properties":{"disabled_at":{"description":"`None` for enabled rows. See\n[`crate::v1::http::management::policies::PolicyEnvelope::disabled_at`]\nfor semantics — toggle via `POST /v1/policies/{id}/disable`\n/ `/enable`.","type":["string","null"],"format":"date-time"},"id":{"type":"string"},"limit_micro_usd":{"type":"integer","format":"int64"},"name":{"type":"string"},"window":{"$ref":"#/$defs/BudgetWindow"}},"required":["id","name","window","limit_micro_usd"]},"BudgetWindow":{"description":"A rolling spend window for [`BudgetSpec`]. Maps to a SQL\ntime-bucket query against `credit_ledger_entries`.","oneOf":[{"description":"24 hours rolling.","type":"string","const":"day"},{"description":"30 days rolling.","type":"string","const":"month"},{"description":"Lifetime — accumulates indefinitely.","type":"string","const":"total"}]}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"post":{"tags":["Management"],"summary":"Create a budget policy","description":"Creates a new budget. `limit_micro_usd` must be strictly positive — the engine treats `<= 0` as \"no policy\", so the API refuses the value up-front.\n\n_Requires the `policy:write` scope._","operationId":"createBudget","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"}],"requestBody":{"description":"Budget request body.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"CreateBudgetRequest","type":"object","properties":{"limit_micro_usd":{"description":"Spend cap in micro-USD. Must be strictly positive — the\nengine treats `<= 0` as \"no policy\" so the API refuses the\npathological value up-front.","type":"integer","format":"int64"},"name":{"type":"string"},"window":{"$ref":"#/$defs/BudgetWindow"}},"required":["name","window","limit_micro_usd"],"$defs":{"BudgetWindow":{"description":"A rolling spend window for [`BudgetSpec`]. Maps to a SQL\ntime-bucket query against `credit_ledger_entries`.","oneOf":[{"description":"24 hours rolling.","type":"string","const":"day"},{"description":"30 days rolling.","type":"string","const":"month"},{"description":"Lifetime — accumulates indefinitely.","type":"string","const":"total"}]}}}}},"required":true},"responses":{"200":{"description":"Created budget.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"BudgetEnvelope","description":"One budget as it appears on the wire. The shape is flat — no\n`kind`/`spec` envelope — because this endpoint only ever produces\nbudgets.","type":"object","properties":{"disabled_at":{"description":"`None` for enabled rows. See\n[`crate::v1::http::management::policies::PolicyEnvelope::disabled_at`]\nfor semantics — toggle via `POST /v1/policies/{id}/disable`\n/ `/enable`.","type":["string","null"],"format":"date-time"},"id":{"type":"string"},"limit_micro_usd":{"type":"integer","format":"int64"},"name":{"type":"string"},"window":{"$ref":"#/$defs/BudgetWindow"}},"required":["id","name","window","limit_micro_usd"],"$defs":{"BudgetWindow":{"description":"A rolling spend window for [`BudgetSpec`]. Maps to a SQL\ntime-bucket query against `credit_ledger_entries`.","oneOf":[{"description":"24 hours rolling.","type":"string","const":"day"},{"description":"30 days rolling.","type":"string","const":"month"},{"description":"Lifetime — accumulates indefinitely.","type":"string","const":"total"}]}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/budgets/{id}":{"get":{"tags":["Management"],"summary":"Read a budget by id","description":"Returns the budget if it exists, belongs to the caller's account, and has `kind = 'budget'`. Any other case yields 404 (no cross-kind or cross-tenant leak).\n\n_Requires the `policy:read` scope._","operationId":"getBudget","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the `policies` row.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Budget row.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"BudgetEnvelope","description":"One budget as it appears on the wire. The shape is flat — no\n`kind`/`spec` envelope — because this endpoint only ever produces\nbudgets.","type":"object","properties":{"disabled_at":{"description":"`None` for enabled rows. See\n[`crate::v1::http::management::policies::PolicyEnvelope::disabled_at`]\nfor semantics — toggle via `POST /v1/policies/{id}/disable`\n/ `/enable`.","type":["string","null"],"format":"date-time"},"id":{"type":"string"},"limit_micro_usd":{"type":"integer","format":"int64"},"name":{"type":"string"},"window":{"$ref":"#/$defs/BudgetWindow"}},"required":["id","name","window","limit_micro_usd"],"$defs":{"BudgetWindow":{"description":"A rolling spend window for [`BudgetSpec`]. Maps to a SQL\ntime-bucket query against `credit_ledger_entries`.","oneOf":[{"description":"24 hours rolling.","type":"string","const":"day"},{"description":"30 days rolling.","type":"string","const":"month"},{"description":"Lifetime — accumulates indefinitely.","type":"string","const":"total"}]}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"put":{"tags":["Management"],"summary":"Update a budget's name, window, or limit","description":"Partial patch. Each field is optional; absent fields are left unchanged. A non-positive `limit_micro_usd` is refused.\n\n_Requires the `policy:write` scope._","operationId":"updateBudget","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the `policies` row.","required":true,"schema":{"type":"string"},"style":"simple"}],"requestBody":{"description":"Budget patch.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"UpdateBudgetRequest","type":"object","properties":{"limit_micro_usd":{"description":"New cap. `None` ⇒ unchanged. When set, must be strictly\npositive.","type":["integer","null"],"format":"int64","default":null},"name":{"description":"New name. `None` ⇒ unchanged.","type":["string","null"],"default":null},"window":{"description":"New window. `None` ⇒ unchanged.","anyOf":[{"$ref":"#/$defs/BudgetWindow"},{"type":"null"}],"default":null}},"$defs":{"BudgetWindow":{"description":"A rolling spend window for [`BudgetSpec`]. Maps to a SQL\ntime-bucket query against `credit_ledger_entries`.","oneOf":[{"description":"24 hours rolling.","type":"string","const":"day"},{"description":"30 days rolling.","type":"string","const":"month"},{"description":"Lifetime — accumulates indefinitely.","type":"string","const":"total"}]}}}}},"required":true},"responses":{"200":{"description":"Updated budget.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"BudgetEnvelope","description":"One budget as it appears on the wire. The shape is flat — no\n`kind`/`spec` envelope — because this endpoint only ever produces\nbudgets.","type":"object","properties":{"disabled_at":{"description":"`None` for enabled rows. See\n[`crate::v1::http::management::policies::PolicyEnvelope::disabled_at`]\nfor semantics — toggle via `POST /v1/policies/{id}/disable`\n/ `/enable`.","type":["string","null"],"format":"date-time"},"id":{"type":"string"},"limit_micro_usd":{"type":"integer","format":"int64"},"name":{"type":"string"},"window":{"$ref":"#/$defs/BudgetWindow"}},"required":["id","name","window","limit_micro_usd"],"$defs":{"BudgetWindow":{"description":"A rolling spend window for [`BudgetSpec`]. Maps to a SQL\ntime-bucket query against `credit_ledger_entries`.","oneOf":[{"description":"24 hours rolling.","type":"string","const":"day"},{"description":"30 days rolling.","type":"string","const":"month"},{"description":"Lifetime — accumulates indefinitely.","type":"string","const":"total"}]}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"delete":{"tags":["Management"],"summary":"Delete a budget and its bindings","description":"Refuses to delete a row whose kind is not `budget` (returns 404). Bindings on the row cascade via the same path as the generic delete.\n\n_Requires the `policy:write` scope._","operationId":"deleteBudget","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the `policies` row.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Delete acknowledgement.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"DeleteBudgetResponse","type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/presets":{"get":{"tags":["Management"],"summary":"List the account's preset bundles","description":"Typed list of `kind = 'preset'` rows. Each preset carries optional `guardrail`, `budget`, and `rate_limit` clauses.\n\n_Requires the `policy:read` scope._","operationId":"listPresets","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Preset list.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"PresetListResponse","type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/$defs/PresetEnvelope"}}},"required":["data"],"$defs":{"Action":{"description":"What to do when a rule matches.","oneOf":[{"description":"Block the content — upstream this is a 400 deny, downstream a stream\nabort. The default when a rule omits its action (block is the safe one).","type":"string","const":"block"},{"description":"Redact the matched span — replace it with the redaction placeholder.","type":"string","const":"redact"}]},"BudgetSpec":{"description":"A spend cap over a rolling window. Spend is measured in\nmicro-USD — the same unit the credit ledger uses, so engine code\ncan sum `credit_ledger_entries.amount_micro_usd` directly.","type":"object","properties":{"limit_micro_usd":{"description":"Spend cap in micro-USD. Must be positive; a non-positive cap\nwould deny every request and is treated as \"no policy\" by the\nengine (it's clamped out during validation in a later phase\nwhen CRUD lands).","type":"integer","format":"int64"},"window":{"$ref":"#/$defs/BudgetWindow"}},"required":["window","limit_micro_usd"]},"BudgetWindow":{"description":"A rolling spend window for [`BudgetSpec`]. Maps to a SQL\ntime-bucket query against `credit_ledger_entries`.","oneOf":[{"description":"24 hours rolling.","type":"string","const":"day"},{"description":"30 days rolling.","type":"string","const":"month"},{"description":"Lifetime — accumulates indefinitely.","type":"string","const":"total"}]},"ByokRequirement":{"description":"Strictness requirement on bring-your-own-key usage for the\ninference call. Mapped from the caller's per-provider BYOK key.","oneOf":[{"description":"The request MUST be served via a BYOK provider key. Used by\nteams who never want platform credits to be spent.","type":"string","const":"required"},{"description":"The request MUST NOT be served via a BYOK key. Useful for\nsuppressing accidental BYOK shadowing on shared namespaces.","type":"string","const":"forbidden"},{"description":"Either path is acceptable. Equivalent to no constraint.","type":"string","const":"optional"}]},"GuardrailSpec":{"description":"Per-request constraints on the inference call (model allowlists,\nmax generation length, streaming / BYOK switches). Each field is\noptional; an unset axis adds no constraint.","type":"object","properties":{"allow_streaming":{"description":"Permit-only one-way gate on streaming responses.\n`Some(false)` forbids streaming: a request with `stream: true`\nis denied. `Some(true)` and `None` both permit streaming\n(`Some(true)` is the explicit \"no constraint here\" form;\n`None` is the absence of any opinion). Guardrails cannot\n*require* streaming — there is no way to refuse a\n`stream: false` request via this field. The combiner\n([`crate::policy::engine`]) is forbid-wins for the same\nreason: the union of permits is still a permit, and any one\n`Some(false)` makes the effective policy a forbid.","type":["boolean","null"]},"byok":{"description":"BYOK posture (see [`ByokRequirement`]). `None` = no\nconstraint.","anyOf":[{"$ref":"#/$defs/ByokRequirement"},{"type":"null"}]},"content_patterns":{"description":"Content-firewall rules: regex `block` / `redact` patterns run over\nthe request prompt and the response stream by the\n`bitrouter-guardrails` hooks. Empty = no content filtering. Combined\nas a union across policies (every rule from every applicable policy\napplies — more rules is strictly more restrictive).","type":"array","items":{"$ref":"#/$defs/RuleSpec"}},"max_request_tokens":{"description":"Hard cap on the request's `prompt.params.max_tokens`. When\nthe request leaves `max_tokens` unset, the call is admitted —\nthe engine can't enforce a cap on an undeclared value.","type":["integer","null"],"format":"int64"},"model_allow":{"description":"If set, only these (canonical) model ids may be requested.\nAn empty allowlist denies every model — same as no policy.","type":["array","null"],"items":{"type":"string"}},"model_deny":{"description":"If set, these model ids are explicitly refused even when the\nallowlist would otherwise admit them. Deny wins over allow.","type":["array","null"],"items":{"type":"string"}}}},"PresetEnvelope":{"description":"One preset as it appears on the wire. The sub-policy fields are\noptional so an empty preset (no clauses) is representable; the\nengine ignores empty presets at request time so this is a no-op\nrow rather than a denial.","type":"object","properties":{"budget":{"anyOf":[{"$ref":"#/$defs/BudgetSpec"},{"type":"null"}]},"disabled_at":{"description":"`None` for enabled rows. See\n[`crate::v1::http::management::policies::PolicyEnvelope::disabled_at`]\nfor semantics — toggle via `POST /v1/policies/{id}/disable`\n/ `/enable`.","type":["string","null"],"format":"date-time"},"guardrail":{"anyOf":[{"$ref":"#/$defs/GuardrailSpec"},{"type":"null"}]},"id":{"type":"string"},"name":{"type":"string"},"rate_limit":{"anyOf":[{"$ref":"#/$defs/RateLimitSpec"},{"type":"null"}]}},"required":["id","name"]},"RateLimitSpec":{"description":"A request-frequency cap over a sliding window. Enforced with\nRedis counters keyed per principal + window. At least one of\n`max_requests` / `max_tokens` must be set for the policy to bite.","type":"object","properties":{"max_requests":{"description":"Hard cap on completed (admitted) requests in the window.","type":["integer","null"],"format":"int64"},"max_tokens":{"description":"Hard cap on the caller's declared prompt-token budget\n(`prompt.params.max_tokens`) in the window. Optional — most\nrate-limit policies in practice only cap request rate.","type":["integer","null"],"format":"int64"},"window_secs":{"description":"Sliding-window width in seconds. Must be positive.","type":"integer","format":"int64"}},"required":["window_secs"]},"RuleSpec":{"description":"One guardrail rule in serializable form: a name, a regex pattern, and a\nmatch action. Compile it into a runtime rule with `RuleSpec::compile`.","type":"object","properties":{"action":{"description":"What to do on a match. Defaults to `block` when omitted.","$ref":"#/$defs/Action","default":"block"},"name":{"description":"Human-readable rule name (surfaced in deny reasons / logs).","type":"string"},"pattern":{"description":"The regex pattern to match.","type":"string"}},"required":["name","pattern"]}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"post":{"tags":["Management"],"summary":"Create a preset bundle","description":"Creates a named bundle of sub-policies. Validation is stricter than the generic create: a rate-limit clause must declare at least one of `max_requests` / `max_tokens`, and `budget.limit_micro_usd` must be strictly positive.\n\n_Requires the `policy:write` scope._","operationId":"createPreset","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"}],"requestBody":{"description":"Preset request body.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"CreatePresetRequest","type":"object","properties":{"budget":{"anyOf":[{"$ref":"#/$defs/BudgetSpec"},{"type":"null"}],"default":null},"guardrail":{"anyOf":[{"$ref":"#/$defs/GuardrailSpec"},{"type":"null"}],"default":null},"name":{"type":"string"},"rate_limit":{"anyOf":[{"$ref":"#/$defs/RateLimitSpec"},{"type":"null"}],"default":null}},"required":["name"],"$defs":{"Action":{"description":"What to do when a rule matches.","oneOf":[{"description":"Block the content — upstream this is a 400 deny, downstream a stream\nabort. The default when a rule omits its action (block is the safe one).","type":"string","const":"block"},{"description":"Redact the matched span — replace it with the redaction placeholder.","type":"string","const":"redact"}]},"BudgetSpec":{"description":"A spend cap over a rolling window. Spend is measured in\nmicro-USD — the same unit the credit ledger uses, so engine code\ncan sum `credit_ledger_entries.amount_micro_usd` directly.","type":"object","properties":{"limit_micro_usd":{"description":"Spend cap in micro-USD. Must be positive; a non-positive cap\nwould deny every request and is treated as \"no policy\" by the\nengine (it's clamped out during validation in a later phase\nwhen CRUD lands).","type":"integer","format":"int64"},"window":{"$ref":"#/$defs/BudgetWindow"}},"required":["window","limit_micro_usd"]},"BudgetWindow":{"description":"A rolling spend window for [`BudgetSpec`]. Maps to a SQL\ntime-bucket query against `credit_ledger_entries`.","oneOf":[{"description":"24 hours rolling.","type":"string","const":"day"},{"description":"30 days rolling.","type":"string","const":"month"},{"description":"Lifetime — accumulates indefinitely.","type":"string","const":"total"}]},"ByokRequirement":{"description":"Strictness requirement on bring-your-own-key usage for the\ninference call. Mapped from the caller's per-provider BYOK key.","oneOf":[{"description":"The request MUST be served via a BYOK provider key. Used by\nteams who never want platform credits to be spent.","type":"string","const":"required"},{"description":"The request MUST NOT be served via a BYOK key. Useful for\nsuppressing accidental BYOK shadowing on shared namespaces.","type":"string","const":"forbidden"},{"description":"Either path is acceptable. Equivalent to no constraint.","type":"string","const":"optional"}]},"GuardrailSpec":{"description":"Per-request constraints on the inference call (model allowlists,\nmax generation length, streaming / BYOK switches). Each field is\noptional; an unset axis adds no constraint.","type":"object","properties":{"allow_streaming":{"description":"Permit-only one-way gate on streaming responses.\n`Some(false)` forbids streaming: a request with `stream: true`\nis denied. `Some(true)` and `None` both permit streaming\n(`Some(true)` is the explicit \"no constraint here\" form;\n`None` is the absence of any opinion). Guardrails cannot\n*require* streaming — there is no way to refuse a\n`stream: false` request via this field. The combiner\n([`crate::policy::engine`]) is forbid-wins for the same\nreason: the union of permits is still a permit, and any one\n`Some(false)` makes the effective policy a forbid.","type":["boolean","null"]},"byok":{"description":"BYOK posture (see [`ByokRequirement`]). `None` = no\nconstraint.","anyOf":[{"$ref":"#/$defs/ByokRequirement"},{"type":"null"}]},"content_patterns":{"description":"Content-firewall rules: regex `block` / `redact` patterns run over\nthe request prompt and the response stream by the\n`bitrouter-guardrails` hooks. Empty = no content filtering. Combined\nas a union across policies (every rule from every applicable policy\napplies — more rules is strictly more restrictive).","type":"array","items":{"$ref":"#/$defs/RuleSpec"}},"max_request_tokens":{"description":"Hard cap on the request's `prompt.params.max_tokens`. When\nthe request leaves `max_tokens` unset, the call is admitted —\nthe engine can't enforce a cap on an undeclared value.","type":["integer","null"],"format":"int64"},"model_allow":{"description":"If set, only these (canonical) model ids may be requested.\nAn empty allowlist denies every model — same as no policy.","type":["array","null"],"items":{"type":"string"}},"model_deny":{"description":"If set, these model ids are explicitly refused even when the\nallowlist would otherwise admit them. Deny wins over allow.","type":["array","null"],"items":{"type":"string"}}}},"RateLimitSpec":{"description":"A request-frequency cap over a sliding window. Enforced with\nRedis counters keyed per principal + window. At least one of\n`max_requests` / `max_tokens` must be set for the policy to bite.","type":"object","properties":{"max_requests":{"description":"Hard cap on completed (admitted) requests in the window.","type":["integer","null"],"format":"int64"},"max_tokens":{"description":"Hard cap on the caller's declared prompt-token budget\n(`prompt.params.max_tokens`) in the window. Optional — most\nrate-limit policies in practice only cap request rate.","type":["integer","null"],"format":"int64"},"window_secs":{"description":"Sliding-window width in seconds. Must be positive.","type":"integer","format":"int64"}},"required":["window_secs"]},"RuleSpec":{"description":"One guardrail rule in serializable form: a name, a regex pattern, and a\nmatch action. Compile it into a runtime rule with `RuleSpec::compile`.","type":"object","properties":{"action":{"description":"What to do on a match. Defaults to `block` when omitted.","$ref":"#/$defs/Action","default":"block"},"name":{"description":"Human-readable rule name (surfaced in deny reasons / logs).","type":"string"},"pattern":{"description":"The regex pattern to match.","type":"string"}},"required":["name","pattern"]}}}}},"required":true},"responses":{"200":{"description":"Created preset.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"PresetEnvelope","description":"One preset as it appears on the wire. The sub-policy fields are\noptional so an empty preset (no clauses) is representable; the\nengine ignores empty presets at request time so this is a no-op\nrow rather than a denial.","type":"object","properties":{"budget":{"anyOf":[{"$ref":"#/$defs/BudgetSpec"},{"type":"null"}]},"disabled_at":{"description":"`None` for enabled rows. See\n[`crate::v1::http::management::policies::PolicyEnvelope::disabled_at`]\nfor semantics — toggle via `POST /v1/policies/{id}/disable`\n/ `/enable`.","type":["string","null"],"format":"date-time"},"guardrail":{"anyOf":[{"$ref":"#/$defs/GuardrailSpec"},{"type":"null"}]},"id":{"type":"string"},"name":{"type":"string"},"rate_limit":{"anyOf":[{"$ref":"#/$defs/RateLimitSpec"},{"type":"null"}]}},"required":["id","name"],"$defs":{"Action":{"description":"What to do when a rule matches.","oneOf":[{"description":"Block the content — upstream this is a 400 deny, downstream a stream\nabort. The default when a rule omits its action (block is the safe one).","type":"string","const":"block"},{"description":"Redact the matched span — replace it with the redaction placeholder.","type":"string","const":"redact"}]},"BudgetSpec":{"description":"A spend cap over a rolling window. Spend is measured in\nmicro-USD — the same unit the credit ledger uses, so engine code\ncan sum `credit_ledger_entries.amount_micro_usd` directly.","type":"object","properties":{"limit_micro_usd":{"description":"Spend cap in micro-USD. Must be positive; a non-positive cap\nwould deny every request and is treated as \"no policy\" by the\nengine (it's clamped out during validation in a later phase\nwhen CRUD lands).","type":"integer","format":"int64"},"window":{"$ref":"#/$defs/BudgetWindow"}},"required":["window","limit_micro_usd"]},"BudgetWindow":{"description":"A rolling spend window for [`BudgetSpec`]. Maps to a SQL\ntime-bucket query against `credit_ledger_entries`.","oneOf":[{"description":"24 hours rolling.","type":"string","const":"day"},{"description":"30 days rolling.","type":"string","const":"month"},{"description":"Lifetime — accumulates indefinitely.","type":"string","const":"total"}]},"ByokRequirement":{"description":"Strictness requirement on bring-your-own-key usage for the\ninference call. Mapped from the caller's per-provider BYOK key.","oneOf":[{"description":"The request MUST be served via a BYOK provider key. Used by\nteams who never want platform credits to be spent.","type":"string","const":"required"},{"description":"The request MUST NOT be served via a BYOK key. Useful for\nsuppressing accidental BYOK shadowing on shared namespaces.","type":"string","const":"forbidden"},{"description":"Either path is acceptable. Equivalent to no constraint.","type":"string","const":"optional"}]},"GuardrailSpec":{"description":"Per-request constraints on the inference call (model allowlists,\nmax generation length, streaming / BYOK switches). Each field is\noptional; an unset axis adds no constraint.","type":"object","properties":{"allow_streaming":{"description":"Permit-only one-way gate on streaming responses.\n`Some(false)` forbids streaming: a request with `stream: true`\nis denied. `Some(true)` and `None` both permit streaming\n(`Some(true)` is the explicit \"no constraint here\" form;\n`None` is the absence of any opinion). Guardrails cannot\n*require* streaming — there is no way to refuse a\n`stream: false` request via this field. The combiner\n([`crate::policy::engine`]) is forbid-wins for the same\nreason: the union of permits is still a permit, and any one\n`Some(false)` makes the effective policy a forbid.","type":["boolean","null"]},"byok":{"description":"BYOK posture (see [`ByokRequirement`]). `None` = no\nconstraint.","anyOf":[{"$ref":"#/$defs/ByokRequirement"},{"type":"null"}]},"content_patterns":{"description":"Content-firewall rules: regex `block` / `redact` patterns run over\nthe request prompt and the response stream by the\n`bitrouter-guardrails` hooks. Empty = no content filtering. Combined\nas a union across policies (every rule from every applicable policy\napplies — more rules is strictly more restrictive).","type":"array","items":{"$ref":"#/$defs/RuleSpec"}},"max_request_tokens":{"description":"Hard cap on the request's `prompt.params.max_tokens`. When\nthe request leaves `max_tokens` unset, the call is admitted —\nthe engine can't enforce a cap on an undeclared value.","type":["integer","null"],"format":"int64"},"model_allow":{"description":"If set, only these (canonical) model ids may be requested.\nAn empty allowlist denies every model — same as no policy.","type":["array","null"],"items":{"type":"string"}},"model_deny":{"description":"If set, these model ids are explicitly refused even when the\nallowlist would otherwise admit them. Deny wins over allow.","type":["array","null"],"items":{"type":"string"}}}},"RateLimitSpec":{"description":"A request-frequency cap over a sliding window. Enforced with\nRedis counters keyed per principal + window. At least one of\n`max_requests` / `max_tokens` must be set for the policy to bite.","type":"object","properties":{"max_requests":{"description":"Hard cap on completed (admitted) requests in the window.","type":["integer","null"],"format":"int64"},"max_tokens":{"description":"Hard cap on the caller's declared prompt-token budget\n(`prompt.params.max_tokens`) in the window. Optional — most\nrate-limit policies in practice only cap request rate.","type":["integer","null"],"format":"int64"},"window_secs":{"description":"Sliding-window width in seconds. Must be positive.","type":"integer","format":"int64"}},"required":["window_secs"]},"RuleSpec":{"description":"One guardrail rule in serializable form: a name, a regex pattern, and a\nmatch action. Compile it into a runtime rule with `RuleSpec::compile`.","type":"object","properties":{"action":{"description":"What to do on a match. Defaults to `block` when omitted.","$ref":"#/$defs/Action","default":"block"},"name":{"description":"Human-readable rule name (surfaced in deny reasons / logs).","type":"string"},"pattern":{"description":"The regex pattern to match.","type":"string"}},"required":["name","pattern"]}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/presets/{id}":{"get":{"tags":["Management"],"summary":"Read a preset by id","description":"Returns the preset if it exists, belongs to the caller's account, and has `kind = 'preset'`. Any other case yields 404.\n\n_Requires the `policy:read` scope._","operationId":"getPreset","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the `policies` row.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Preset row.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"PresetEnvelope","description":"One preset as it appears on the wire. The sub-policy fields are\noptional so an empty preset (no clauses) is representable; the\nengine ignores empty presets at request time so this is a no-op\nrow rather than a denial.","type":"object","properties":{"budget":{"anyOf":[{"$ref":"#/$defs/BudgetSpec"},{"type":"null"}]},"disabled_at":{"description":"`None` for enabled rows. See\n[`crate::v1::http::management::policies::PolicyEnvelope::disabled_at`]\nfor semantics — toggle via `POST /v1/policies/{id}/disable`\n/ `/enable`.","type":["string","null"],"format":"date-time"},"guardrail":{"anyOf":[{"$ref":"#/$defs/GuardrailSpec"},{"type":"null"}]},"id":{"type":"string"},"name":{"type":"string"},"rate_limit":{"anyOf":[{"$ref":"#/$defs/RateLimitSpec"},{"type":"null"}]}},"required":["id","name"],"$defs":{"Action":{"description":"What to do when a rule matches.","oneOf":[{"description":"Block the content — upstream this is a 400 deny, downstream a stream\nabort. The default when a rule omits its action (block is the safe one).","type":"string","const":"block"},{"description":"Redact the matched span — replace it with the redaction placeholder.","type":"string","const":"redact"}]},"BudgetSpec":{"description":"A spend cap over a rolling window. Spend is measured in\nmicro-USD — the same unit the credit ledger uses, so engine code\ncan sum `credit_ledger_entries.amount_micro_usd` directly.","type":"object","properties":{"limit_micro_usd":{"description":"Spend cap in micro-USD. Must be positive; a non-positive cap\nwould deny every request and is treated as \"no policy\" by the\nengine (it's clamped out during validation in a later phase\nwhen CRUD lands).","type":"integer","format":"int64"},"window":{"$ref":"#/$defs/BudgetWindow"}},"required":["window","limit_micro_usd"]},"BudgetWindow":{"description":"A rolling spend window for [`BudgetSpec`]. Maps to a SQL\ntime-bucket query against `credit_ledger_entries`.","oneOf":[{"description":"24 hours rolling.","type":"string","const":"day"},{"description":"30 days rolling.","type":"string","const":"month"},{"description":"Lifetime — accumulates indefinitely.","type":"string","const":"total"}]},"ByokRequirement":{"description":"Strictness requirement on bring-your-own-key usage for the\ninference call. Mapped from the caller's per-provider BYOK key.","oneOf":[{"description":"The request MUST be served via a BYOK provider key. Used by\nteams who never want platform credits to be spent.","type":"string","const":"required"},{"description":"The request MUST NOT be served via a BYOK key. Useful for\nsuppressing accidental BYOK shadowing on shared namespaces.","type":"string","const":"forbidden"},{"description":"Either path is acceptable. Equivalent to no constraint.","type":"string","const":"optional"}]},"GuardrailSpec":{"description":"Per-request constraints on the inference call (model allowlists,\nmax generation length, streaming / BYOK switches). Each field is\noptional; an unset axis adds no constraint.","type":"object","properties":{"allow_streaming":{"description":"Permit-only one-way gate on streaming responses.\n`Some(false)` forbids streaming: a request with `stream: true`\nis denied. `Some(true)` and `None` both permit streaming\n(`Some(true)` is the explicit \"no constraint here\" form;\n`None` is the absence of any opinion). Guardrails cannot\n*require* streaming — there is no way to refuse a\n`stream: false` request via this field. The combiner\n([`crate::policy::engine`]) is forbid-wins for the same\nreason: the union of permits is still a permit, and any one\n`Some(false)` makes the effective policy a forbid.","type":["boolean","null"]},"byok":{"description":"BYOK posture (see [`ByokRequirement`]). `None` = no\nconstraint.","anyOf":[{"$ref":"#/$defs/ByokRequirement"},{"type":"null"}]},"content_patterns":{"description":"Content-firewall rules: regex `block` / `redact` patterns run over\nthe request prompt and the response stream by the\n`bitrouter-guardrails` hooks. Empty = no content filtering. Combined\nas a union across policies (every rule from every applicable policy\napplies — more rules is strictly more restrictive).","type":"array","items":{"$ref":"#/$defs/RuleSpec"}},"max_request_tokens":{"description":"Hard cap on the request's `prompt.params.max_tokens`. When\nthe request leaves `max_tokens` unset, the call is admitted —\nthe engine can't enforce a cap on an undeclared value.","type":["integer","null"],"format":"int64"},"model_allow":{"description":"If set, only these (canonical) model ids may be requested.\nAn empty allowlist denies every model — same as no policy.","type":["array","null"],"items":{"type":"string"}},"model_deny":{"description":"If set, these model ids are explicitly refused even when the\nallowlist would otherwise admit them. Deny wins over allow.","type":["array","null"],"items":{"type":"string"}}}},"RateLimitSpec":{"description":"A request-frequency cap over a sliding window. Enforced with\nRedis counters keyed per principal + window. At least one of\n`max_requests` / `max_tokens` must be set for the policy to bite.","type":"object","properties":{"max_requests":{"description":"Hard cap on completed (admitted) requests in the window.","type":["integer","null"],"format":"int64"},"max_tokens":{"description":"Hard cap on the caller's declared prompt-token budget\n(`prompt.params.max_tokens`) in the window. Optional — most\nrate-limit policies in practice only cap request rate.","type":["integer","null"],"format":"int64"},"window_secs":{"description":"Sliding-window width in seconds. Must be positive.","type":"integer","format":"int64"}},"required":["window_secs"]},"RuleSpec":{"description":"One guardrail rule in serializable form: a name, a regex pattern, and a\nmatch action. Compile it into a runtime rule with `RuleSpec::compile`.","type":"object","properties":{"action":{"description":"What to do on a match. Defaults to `block` when omitted.","$ref":"#/$defs/Action","default":"block"},"name":{"description":"Human-readable rule name (surfaced in deny reasons / logs).","type":"string"},"pattern":{"description":"The regex pattern to match.","type":"string"}},"required":["name","pattern"]}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"put":{"tags":["Management"],"summary":"Update a preset's name or clauses","description":"Partial patch. Each clause replacement is optional; an absent clause is left unchanged. Use the explicit `clear_guardrail` / `clear_budget` / `clear_rate_limit` flags to remove a clause — `null` body fields are NOT interpreted as clears.\n\n_Requires the `policy:write` scope._","operationId":"updatePreset","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the `policies` row.","required":true,"schema":{"type":"string"},"style":"simple"}],"requestBody":{"description":"Preset patch.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"UpdatePresetRequest","description":"Partial update for a preset. Each clause is independently\noptional: `None` means \"leave this clause unchanged\"; a\nJSON `null` (deserialised as `Some(None)` via\n`#[serde(default, with = \"serde_with::rust::double_option\")]`\n— not used here, see the explicit `clear_*` flags) is not\nsupported. Use the explicit `clear_*` flags to remove a clause.\n\nThis shape was chosen over `serde_with::double_option` because\n`Option<Option<T>>` is awkward for callers and the `clear_*`\nflag is unambiguous on the wire.","type":"object","properties":{"budget":{"description":"Replace the budget clause. `None` ⇒ unchanged.","anyOf":[{"$ref":"#/$defs/BudgetSpec"},{"type":"null"}],"default":null},"clear_budget":{"type":"boolean","default":false},"clear_guardrail":{"description":"When true, drop the guardrail clause from the stored preset.\nOverrides `guardrail` if both are present (the spec body\nwould have to be re-set on a subsequent PUT to add it back).","type":"boolean","default":false},"clear_rate_limit":{"type":"boolean","default":false},"guardrail":{"description":"Replace the guardrail clause. `None` ⇒ unchanged.","anyOf":[{"$ref":"#/$defs/GuardrailSpec"},{"type":"null"}],"default":null},"name":{"description":"New name. `None` ⇒ unchanged.","type":["string","null"],"default":null},"rate_limit":{"description":"Replace the rate-limit clause. `None` ⇒ unchanged.","anyOf":[{"$ref":"#/$defs/RateLimitSpec"},{"type":"null"}],"default":null}},"$defs":{"Action":{"description":"What to do when a rule matches.","oneOf":[{"description":"Block the content — upstream this is a 400 deny, downstream a stream\nabort. The default when a rule omits its action (block is the safe one).","type":"string","const":"block"},{"description":"Redact the matched span — replace it with the redaction placeholder.","type":"string","const":"redact"}]},"BudgetSpec":{"description":"A spend cap over a rolling window. Spend is measured in\nmicro-USD — the same unit the credit ledger uses, so engine code\ncan sum `credit_ledger_entries.amount_micro_usd` directly.","type":"object","properties":{"limit_micro_usd":{"description":"Spend cap in micro-USD. Must be positive; a non-positive cap\nwould deny every request and is treated as \"no policy\" by the\nengine (it's clamped out during validation in a later phase\nwhen CRUD lands).","type":"integer","format":"int64"},"window":{"$ref":"#/$defs/BudgetWindow"}},"required":["window","limit_micro_usd"]},"BudgetWindow":{"description":"A rolling spend window for [`BudgetSpec`]. Maps to a SQL\ntime-bucket query against `credit_ledger_entries`.","oneOf":[{"description":"24 hours rolling.","type":"string","const":"day"},{"description":"30 days rolling.","type":"string","const":"month"},{"description":"Lifetime — accumulates indefinitely.","type":"string","const":"total"}]},"ByokRequirement":{"description":"Strictness requirement on bring-your-own-key usage for the\ninference call. Mapped from the caller's per-provider BYOK key.","oneOf":[{"description":"The request MUST be served via a BYOK provider key. Used by\nteams who never want platform credits to be spent.","type":"string","const":"required"},{"description":"The request MUST NOT be served via a BYOK key. Useful for\nsuppressing accidental BYOK shadowing on shared namespaces.","type":"string","const":"forbidden"},{"description":"Either path is acceptable. Equivalent to no constraint.","type":"string","const":"optional"}]},"GuardrailSpec":{"description":"Per-request constraints on the inference call (model allowlists,\nmax generation length, streaming / BYOK switches). Each field is\noptional; an unset axis adds no constraint.","type":"object","properties":{"allow_streaming":{"description":"Permit-only one-way gate on streaming responses.\n`Some(false)` forbids streaming: a request with `stream: true`\nis denied. `Some(true)` and `None` both permit streaming\n(`Some(true)` is the explicit \"no constraint here\" form;\n`None` is the absence of any opinion). Guardrails cannot\n*require* streaming — there is no way to refuse a\n`stream: false` request via this field. The combiner\n([`crate::policy::engine`]) is forbid-wins for the same\nreason: the union of permits is still a permit, and any one\n`Some(false)` makes the effective policy a forbid.","type":["boolean","null"]},"byok":{"description":"BYOK posture (see [`ByokRequirement`]). `None` = no\nconstraint.","anyOf":[{"$ref":"#/$defs/ByokRequirement"},{"type":"null"}]},"content_patterns":{"description":"Content-firewall rules: regex `block` / `redact` patterns run over\nthe request prompt and the response stream by the\n`bitrouter-guardrails` hooks. Empty = no content filtering. Combined\nas a union across policies (every rule from every applicable policy\napplies — more rules is strictly more restrictive).","type":"array","items":{"$ref":"#/$defs/RuleSpec"}},"max_request_tokens":{"description":"Hard cap on the request's `prompt.params.max_tokens`. When\nthe request leaves `max_tokens` unset, the call is admitted —\nthe engine can't enforce a cap on an undeclared value.","type":["integer","null"],"format":"int64"},"model_allow":{"description":"If set, only these (canonical) model ids may be requested.\nAn empty allowlist denies every model — same as no policy.","type":["array","null"],"items":{"type":"string"}},"model_deny":{"description":"If set, these model ids are explicitly refused even when the\nallowlist would otherwise admit them. Deny wins over allow.","type":["array","null"],"items":{"type":"string"}}}},"RateLimitSpec":{"description":"A request-frequency cap over a sliding window. Enforced with\nRedis counters keyed per principal + window. At least one of\n`max_requests` / `max_tokens` must be set for the policy to bite.","type":"object","properties":{"max_requests":{"description":"Hard cap on completed (admitted) requests in the window.","type":["integer","null"],"format":"int64"},"max_tokens":{"description":"Hard cap on the caller's declared prompt-token budget\n(`prompt.params.max_tokens`) in the window. Optional — most\nrate-limit policies in practice only cap request rate.","type":["integer","null"],"format":"int64"},"window_secs":{"description":"Sliding-window width in seconds. Must be positive.","type":"integer","format":"int64"}},"required":["window_secs"]},"RuleSpec":{"description":"One guardrail rule in serializable form: a name, a regex pattern, and a\nmatch action. Compile it into a runtime rule with `RuleSpec::compile`.","type":"object","properties":{"action":{"description":"What to do on a match. Defaults to `block` when omitted.","$ref":"#/$defs/Action","default":"block"},"name":{"description":"Human-readable rule name (surfaced in deny reasons / logs).","type":"string"},"pattern":{"description":"The regex pattern to match.","type":"string"}},"required":["name","pattern"]}}}}},"required":true},"responses":{"200":{"description":"Updated preset.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"PresetEnvelope","description":"One preset as it appears on the wire. The sub-policy fields are\noptional so an empty preset (no clauses) is representable; the\nengine ignores empty presets at request time so this is a no-op\nrow rather than a denial.","type":"object","properties":{"budget":{"anyOf":[{"$ref":"#/$defs/BudgetSpec"},{"type":"null"}]},"disabled_at":{"description":"`None` for enabled rows. See\n[`crate::v1::http::management::policies::PolicyEnvelope::disabled_at`]\nfor semantics — toggle via `POST /v1/policies/{id}/disable`\n/ `/enable`.","type":["string","null"],"format":"date-time"},"guardrail":{"anyOf":[{"$ref":"#/$defs/GuardrailSpec"},{"type":"null"}]},"id":{"type":"string"},"name":{"type":"string"},"rate_limit":{"anyOf":[{"$ref":"#/$defs/RateLimitSpec"},{"type":"null"}]}},"required":["id","name"],"$defs":{"Action":{"description":"What to do when a rule matches.","oneOf":[{"description":"Block the content — upstream this is a 400 deny, downstream a stream\nabort. The default when a rule omits its action (block is the safe one).","type":"string","const":"block"},{"description":"Redact the matched span — replace it with the redaction placeholder.","type":"string","const":"redact"}]},"BudgetSpec":{"description":"A spend cap over a rolling window. Spend is measured in\nmicro-USD — the same unit the credit ledger uses, so engine code\ncan sum `credit_ledger_entries.amount_micro_usd` directly.","type":"object","properties":{"limit_micro_usd":{"description":"Spend cap in micro-USD. Must be positive; a non-positive cap\nwould deny every request and is treated as \"no policy\" by the\nengine (it's clamped out during validation in a later phase\nwhen CRUD lands).","type":"integer","format":"int64"},"window":{"$ref":"#/$defs/BudgetWindow"}},"required":["window","limit_micro_usd"]},"BudgetWindow":{"description":"A rolling spend window for [`BudgetSpec`]. Maps to a SQL\ntime-bucket query against `credit_ledger_entries`.","oneOf":[{"description":"24 hours rolling.","type":"string","const":"day"},{"description":"30 days rolling.","type":"string","const":"month"},{"description":"Lifetime — accumulates indefinitely.","type":"string","const":"total"}]},"ByokRequirement":{"description":"Strictness requirement on bring-your-own-key usage for the\ninference call. Mapped from the caller's per-provider BYOK key.","oneOf":[{"description":"The request MUST be served via a BYOK provider key. Used by\nteams who never want platform credits to be spent.","type":"string","const":"required"},{"description":"The request MUST NOT be served via a BYOK key. Useful for\nsuppressing accidental BYOK shadowing on shared namespaces.","type":"string","const":"forbidden"},{"description":"Either path is acceptable. Equivalent to no constraint.","type":"string","const":"optional"}]},"GuardrailSpec":{"description":"Per-request constraints on the inference call (model allowlists,\nmax generation length, streaming / BYOK switches). Each field is\noptional; an unset axis adds no constraint.","type":"object","properties":{"allow_streaming":{"description":"Permit-only one-way gate on streaming responses.\n`Some(false)` forbids streaming: a request with `stream: true`\nis denied. `Some(true)` and `None` both permit streaming\n(`Some(true)` is the explicit \"no constraint here\" form;\n`None` is the absence of any opinion). Guardrails cannot\n*require* streaming — there is no way to refuse a\n`stream: false` request via this field. The combiner\n([`crate::policy::engine`]) is forbid-wins for the same\nreason: the union of permits is still a permit, and any one\n`Some(false)` makes the effective policy a forbid.","type":["boolean","null"]},"byok":{"description":"BYOK posture (see [`ByokRequirement`]). `None` = no\nconstraint.","anyOf":[{"$ref":"#/$defs/ByokRequirement"},{"type":"null"}]},"content_patterns":{"description":"Content-firewall rules: regex `block` / `redact` patterns run over\nthe request prompt and the response stream by the\n`bitrouter-guardrails` hooks. Empty = no content filtering. Combined\nas a union across policies (every rule from every applicable policy\napplies — more rules is strictly more restrictive).","type":"array","items":{"$ref":"#/$defs/RuleSpec"}},"max_request_tokens":{"description":"Hard cap on the request's `prompt.params.max_tokens`. When\nthe request leaves `max_tokens` unset, the call is admitted —\nthe engine can't enforce a cap on an undeclared value.","type":["integer","null"],"format":"int64"},"model_allow":{"description":"If set, only these (canonical) model ids may be requested.\nAn empty allowlist denies every model — same as no policy.","type":["array","null"],"items":{"type":"string"}},"model_deny":{"description":"If set, these model ids are explicitly refused even when the\nallowlist would otherwise admit them. Deny wins over allow.","type":["array","null"],"items":{"type":"string"}}}},"RateLimitSpec":{"description":"A request-frequency cap over a sliding window. Enforced with\nRedis counters keyed per principal + window. At least one of\n`max_requests` / `max_tokens` must be set for the policy to bite.","type":"object","properties":{"max_requests":{"description":"Hard cap on completed (admitted) requests in the window.","type":["integer","null"],"format":"int64"},"max_tokens":{"description":"Hard cap on the caller's declared prompt-token budget\n(`prompt.params.max_tokens`) in the window. Optional — most\nrate-limit policies in practice only cap request rate.","type":["integer","null"],"format":"int64"},"window_secs":{"description":"Sliding-window width in seconds. Must be positive.","type":"integer","format":"int64"}},"required":["window_secs"]},"RuleSpec":{"description":"One guardrail rule in serializable form: a name, a regex pattern, and a\nmatch action. Compile it into a runtime rule with `RuleSpec::compile`.","type":"object","properties":{"action":{"description":"What to do on a match. Defaults to `block` when omitted.","$ref":"#/$defs/Action","default":"block"},"name":{"description":"Human-readable rule name (surfaced in deny reasons / logs).","type":"string"},"pattern":{"description":"The regex pattern to match.","type":"string"}},"required":["name","pattern"]}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"delete":{"tags":["Management"],"summary":"Delete a preset and its bindings","description":"Refuses to delete a row whose kind is not `preset` (returns 404).\n\n_Requires the `policy:write` scope._","operationId":"deletePreset","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the `policies` row.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Delete acknowledgement.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"DeletePresetResponse","type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/routing-presets":{"get":{"tags":["Management"],"summary":"List the namespace's routing presets","description":"Typed list of routing presets. Each preset bundles request defaults (`model`, `system_prompt`, generation `params`) with provider-routing constraints (`routing`).\n\n_Requires the `routing_preset:read` scope._","operationId":"listRoutingPresets","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Routing preset list.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"RoutingPresetListResponse","type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/$defs/RoutingPresetEnvelope"}}},"required":["data"],"$defs":{"RoutingConfig":{"description":"Provider-routing constraints carried by a preset. All fields optional;\nan empty `RoutingConfig` is a valid no-op.","type":"object","properties":{"ignore":{"description":"Provider deny-list (`provider_name`).","type":"array","items":{"type":"string"}},"only":{"description":"Provider allow-list (`provider_name`). Empty = no restriction.","type":"array","items":{"type":"string"}},"sort":{"description":"Optimization axis; reuses the global `RoutingProfile` vocabulary.","type":["string","null"]}}},"RoutingPresetEnvelope":{"description":"One routing preset as it appears on the wire. The spec fields are\nflattened alongside `id` / `name`; `disabled_at` is `None` for\nenabled rows.","type":"object","properties":{"disabled_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"string"},"model":{"description":"Base model substitution. When absent, the request must supply a base.","type":["string","null"]},"name":{"type":"string"},"params":{"description":"Generation-param defaults, shallow-merged into the request (request wins).","type":"object","additionalProperties":true},"routing":{"description":"Routing constraints.","$ref":"#/$defs/RoutingConfig"},"system_prompt":{"description":"System-prompt default (filled only if the request omits one).","type":["string","null"]}},"required":["id","name"]}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"post":{"tags":["Management"],"summary":"Create a routing preset","description":"Creates a named bundle of request defaults plus routing constraints, selectable per-request via `@<name>`. The request pipeline shallow-merges the preset's fields into the inbound request.\n\n_Requires the `routing_preset:write` scope._","operationId":"createRoutingPreset","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"}],"requestBody":{"description":"Routing preset request body.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"CreateRoutingPresetRequest","type":"object","properties":{"model":{"type":["string","null"],"default":null},"name":{"type":"string"},"params":{"type":"object","additionalProperties":true,"default":{}},"routing":{"$ref":"#/$defs/RoutingConfig","default":{}},"system_prompt":{"type":["string","null"],"default":null}},"required":["name"],"$defs":{"RoutingConfig":{"description":"Provider-routing constraints carried by a preset. All fields optional;\nan empty `RoutingConfig` is a valid no-op.","type":"object","properties":{"ignore":{"description":"Provider deny-list (`provider_name`).","type":"array","items":{"type":"string"}},"only":{"description":"Provider allow-list (`provider_name`). Empty = no restriction.","type":"array","items":{"type":"string"}},"sort":{"description":"Optimization axis; reuses the global `RoutingProfile` vocabulary.","type":["string","null"]}}}}}}},"required":true},"responses":{"200":{"description":"Created routing preset.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"RoutingPresetEnvelope","description":"One routing preset as it appears on the wire. The spec fields are\nflattened alongside `id` / `name`; `disabled_at` is `None` for\nenabled rows.","type":"object","properties":{"disabled_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"string"},"model":{"description":"Base model substitution. When absent, the request must supply a base.","type":["string","null"]},"name":{"type":"string"},"params":{"description":"Generation-param defaults, shallow-merged into the request (request wins).","type":"object","additionalProperties":true},"routing":{"description":"Routing constraints.","$ref":"#/$defs/RoutingConfig"},"system_prompt":{"description":"System-prompt default (filled only if the request omits one).","type":["string","null"]}},"required":["id","name"],"$defs":{"RoutingConfig":{"description":"Provider-routing constraints carried by a preset. All fields optional;\nan empty `RoutingConfig` is a valid no-op.","type":"object","properties":{"ignore":{"description":"Provider deny-list (`provider_name`).","type":"array","items":{"type":"string"}},"only":{"description":"Provider allow-list (`provider_name`). Empty = no restriction.","type":"array","items":{"type":"string"}},"sort":{"description":"Optimization axis; reuses the global `RoutingProfile` vocabulary.","type":["string","null"]}}}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/routing-presets/{id}":{"get":{"tags":["Management"],"summary":"Read a routing preset by id","description":"Returns the routing preset if it exists and belongs to the named namespace. Any other case yields 404.\n\n_Requires the `routing_preset:read` scope._","operationId":"getRoutingPreset","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the `routing_presets` row.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Routing preset row.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"RoutingPresetEnvelope","description":"One routing preset as it appears on the wire. The spec fields are\nflattened alongside `id` / `name`; `disabled_at` is `None` for\nenabled rows.","type":"object","properties":{"disabled_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"string"},"model":{"description":"Base model substitution. When absent, the request must supply a base.","type":["string","null"]},"name":{"type":"string"},"params":{"description":"Generation-param defaults, shallow-merged into the request (request wins).","type":"object","additionalProperties":true},"routing":{"description":"Routing constraints.","$ref":"#/$defs/RoutingConfig"},"system_prompt":{"description":"System-prompt default (filled only if the request omits one).","type":["string","null"]}},"required":["id","name"],"$defs":{"RoutingConfig":{"description":"Provider-routing constraints carried by a preset. All fields optional;\nan empty `RoutingConfig` is a valid no-op.","type":"object","properties":{"ignore":{"description":"Provider deny-list (`provider_name`).","type":"array","items":{"type":"string"}},"only":{"description":"Provider allow-list (`provider_name`). Empty = no restriction.","type":"array","items":{"type":"string"}},"sort":{"description":"Optimization axis; reuses the global `RoutingProfile` vocabulary.","type":["string","null"]}}}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"put":{"tags":["Management"],"summary":"Replace a routing preset's spec","description":"Full replace of the preset's spec body (not a per-field merge) — every request carries the complete spec it wants persisted. `name` is optional; an absent `name` leaves it unchanged.\n\n_Requires the `routing_preset:write` scope._","operationId":"updateRoutingPreset","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the `routing_presets` row.","required":true,"schema":{"type":"string"},"style":"simple"}],"requestBody":{"description":"Routing preset replacement.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"UpdateRoutingPresetRequest","type":"object","properties":{"model":{"type":["string","null"],"default":null},"name":{"type":["string","null"],"default":null},"params":{"type":"object","additionalProperties":true,"default":{}},"routing":{"$ref":"#/$defs/RoutingConfig","default":{}},"system_prompt":{"type":["string","null"],"default":null}},"$defs":{"RoutingConfig":{"description":"Provider-routing constraints carried by a preset. All fields optional;\nan empty `RoutingConfig` is a valid no-op.","type":"object","properties":{"ignore":{"description":"Provider deny-list (`provider_name`).","type":"array","items":{"type":"string"}},"only":{"description":"Provider allow-list (`provider_name`). Empty = no restriction.","type":"array","items":{"type":"string"}},"sort":{"description":"Optimization axis; reuses the global `RoutingProfile` vocabulary.","type":["string","null"]}}}}}}},"required":true},"responses":{"200":{"description":"Updated routing preset.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"RoutingPresetEnvelope","description":"One routing preset as it appears on the wire. The spec fields are\nflattened alongside `id` / `name`; `disabled_at` is `None` for\nenabled rows.","type":"object","properties":{"disabled_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"string"},"model":{"description":"Base model substitution. When absent, the request must supply a base.","type":["string","null"]},"name":{"type":"string"},"params":{"description":"Generation-param defaults, shallow-merged into the request (request wins).","type":"object","additionalProperties":true},"routing":{"description":"Routing constraints.","$ref":"#/$defs/RoutingConfig"},"system_prompt":{"description":"System-prompt default (filled only if the request omits one).","type":["string","null"]}},"required":["id","name"],"$defs":{"RoutingConfig":{"description":"Provider-routing constraints carried by a preset. All fields optional;\nan empty `RoutingConfig` is a valid no-op.","type":"object","properties":{"ignore":{"description":"Provider deny-list (`provider_name`).","type":"array","items":{"type":"string"}},"only":{"description":"Provider allow-list (`provider_name`). Empty = no restriction.","type":"array","items":{"type":"string"}},"sort":{"description":"Optimization axis; reuses the global `RoutingProfile` vocabulary.","type":["string","null"]}}}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"delete":{"tags":["Management"],"summary":"Delete a routing preset","description":"Deletes the routing preset by id within the named namespace. Returns 404 if no such row exists in the namespace.\n\n_Requires the `routing_preset:write` scope._","operationId":"deleteRoutingPreset","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the `routing_presets` row.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Delete acknowledgement.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"DeleteRoutingPresetResponse","type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/routing-presets/{id}/disable":{"post":{"tags":["Management"],"summary":"Park a routing preset without deleting it","description":"Stamps `disabled_at = now()`. The resolver skips disabled presets when selecting a preset per-request; the management surface still surfaces them so an operator can re-enable. Idempotent — re-disabling returns 200. Responds with the updated envelope carrying `disabled_at`.\n\n_Requires the `routing_preset:write` scope._","operationId":"disableRoutingPreset","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the `routing_presets` row.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Updated routing preset.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"RoutingPresetEnvelope","description":"One routing preset as it appears on the wire. The spec fields are\nflattened alongside `id` / `name`; `disabled_at` is `None` for\nenabled rows.","type":"object","properties":{"disabled_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"string"},"model":{"description":"Base model substitution. When absent, the request must supply a base.","type":["string","null"]},"name":{"type":"string"},"params":{"description":"Generation-param defaults, shallow-merged into the request (request wins).","type":"object","additionalProperties":true},"routing":{"description":"Routing constraints.","$ref":"#/$defs/RoutingConfig"},"system_prompt":{"description":"System-prompt default (filled only if the request omits one).","type":["string","null"]}},"required":["id","name"],"$defs":{"RoutingConfig":{"description":"Provider-routing constraints carried by a preset. All fields optional;\nan empty `RoutingConfig` is a valid no-op.","type":"object","properties":{"ignore":{"description":"Provider deny-list (`provider_name`).","type":"array","items":{"type":"string"}},"only":{"description":"Provider allow-list (`provider_name`). Empty = no restriction.","type":"array","items":{"type":"string"}},"sort":{"description":"Optimization axis; reuses the global `RoutingProfile` vocabulary.","type":["string","null"]}}}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/routing-presets/{id}/enable":{"post":{"tags":["Management"],"summary":"Re-enable a previously disabled routing preset","description":"Clears `disabled_at`. The resolver starts honouring the preset again on the next request. Idempotent. Responds with the updated envelope (with `disabled_at` cleared).\n\n_Requires the `routing_preset:write` scope._","operationId":"enableRoutingPreset","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"id","description":"Surrogate id of the `routing_presets` row.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Updated routing preset.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"RoutingPresetEnvelope","description":"One routing preset as it appears on the wire. The spec fields are\nflattened alongside `id` / `name`; `disabled_at` is `None` for\nenabled rows.","type":"object","properties":{"disabled_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"string"},"model":{"description":"Base model substitution. When absent, the request must supply a base.","type":["string","null"]},"name":{"type":"string"},"params":{"description":"Generation-param defaults, shallow-merged into the request (request wins).","type":"object","additionalProperties":true},"routing":{"description":"Routing constraints.","$ref":"#/$defs/RoutingConfig"},"system_prompt":{"description":"System-prompt default (filled only if the request omits one).","type":["string","null"]}},"required":["id","name"],"$defs":{"RoutingConfig":{"description":"Provider-routing constraints carried by a preset. All fields optional;\nan empty `RoutingConfig` is a valid no-op.","type":"object","properties":{"ignore":{"description":"Provider deny-list (`provider_name`).","type":"array","items":{"type":"string"}},"only":{"description":"Provider allow-list (`provider_name`). Empty = no restriction.","type":"array","items":{"type":"string"}},"sort":{"description":"Optimization axis; reuses the global `RoutingProfile` vocabulary.","type":["string","null"]}}}}}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/oauth/clients":{"get":{"tags":["Management"],"summary":"List the caller's OAuth clients","description":"Never returns the `client_secret_hash`.\n\n_Requires the `clients:read` scope._","operationId":"listOauthClients","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"post":{"tags":["Management"],"summary":"Register a new OAuth client","description":"Confidential clients receive the freshly minted `client_secret` once in the response — the cloud retains only the hash.\n\n_Requires the `clients:write` scope._","operationId":"registerOauthClient","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"}],"requestBody":{"description":"Request body. See the endpoint description for shape.","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/namespaces/{nsid}/oauth/clients/{client_id}":{"put":{"tags":["Management"],"summary":"Update an OAuth client","description":"Mutate the client's name, redirect URIs, allowed scopes, or allowed grant types. Each field is optional.\n\n_Requires the `clients:write` scope._","operationId":"updateOauthClient","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"}],"requestBody":{"description":"Request body. See the endpoint description for shape.","content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"delete":{"tags":["Management"],"summary":"Delete an OAuth client","description":"\n\n_Requires the `clients:write` scope._","operationId":"deleteOauthClient","parameters":[{"in":"path","name":"nsid","description":"Id of the target namespace. Must be owned by the caller (or equal a namespace-baked credential's own namespace), else 404.","required":true,"schema":{"type":"string"},"style":"simple"},{"in":"path","name":"client_id","description":"The client's public `client_id` (e.g. `brc_…`).","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Credential missing or did not verify.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"403":{"description":"Credential is valid but lacks the required scope.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}},"404":{"description":"Resource not found (or owned by a different account).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ManagementErrorResponseDoc","description":"Management API error envelope. This intentionally differs from the\nOpenAI-compatible inference error shape above.","type":"object","properties":{"error":{"description":"Stable management error name.","type":"string"},"error_description":{"description":"Human-readable management error description.","type":"string"}},"required":["error","error_description"]}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/chat/completions":{"post":{"tags":["OpenAI Compatible"],"summary":"Create chat completion","description":"Creates a chat completion for the given messages. Drop-in replacement for the OpenAI Chat Completions API — accepts the same request schema and returns the same response format, including `usage` with token counts.\n\nThe router resolves the requested model to an upstream provider, forwards the request, and returns the response. Supports both synchronous and streaming modes.\n\nWhen `stream: true`, the response is sent as Server-Sent Events (SSE) where each `data` line contains a `ChatCompletionChunk` JSON object. The stream ends with `data: [DONE]`.","operationId":"createChatCompletion","requestBody":{"description":"Chat completion request. The router forwards a slightly enriched version of this body to the resolved upstream provider.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ChatRequest","description":"Chat Completions request body\n(<https://platform.openai.com/docs/api-reference/chat/create>).\n\n`pub` so downstream crates (notably `bitrouter-cloud`) can derive an\nOpenAPI schema from the canonical wire shape without redeclaring it.","type":"object","properties":{"frequency_penalty":{"description":"Frequency penalty. Promoted to the canonical `frequency_penalty` slot.\n<https://platform.openai.com/docs/api-reference/chat/create#chat-create-frequency_penalty>","type":["number","null"],"format":"double","default":null},"max_completion_tokens":{"type":["integer","null"],"format":"uint32","default":null,"minimum":0},"max_tokens":{"type":["integer","null"],"format":"uint32","default":null,"minimum":0},"messages":{"type":"array","items":{"$ref":"#/$defs/ChatMessage"}},"model":{"type":"string"},"parallel_tool_calls":{"description":"Whether the model may issue tool calls in parallel.","type":["boolean","null"],"default":null},"presence_penalty":{"description":"Presence penalty. Promoted to the canonical `presence_penalty` slot.\n<https://platform.openai.com/docs/api-reference/chat/create#chat-create-presence_penalty>","type":["number","null"],"format":"double","default":null},"reasoning_effort":{"anyOf":[{"$ref":"#/$defs/ReasoningEffort"},{"type":"null"}],"default":null},"response_format":{"description":"Output-format constraint. The `json_schema` variant is the\nstructured-output contract; `json_object` is the legacy JSON mode and\n`text` is the default. Promoted to the canonical `response_format` slot\nat parse time (`json_object` / `text` pass through opaquely).\n<https://platform.openai.com/docs/guides/structured-outputs>","anyOf":[{"$ref":"#/$defs/ChatResponseFormat"},{"type":"null"}],"default":null},"seed":{"description":"Deterministic-sampling seed. Promoted to the canonical `seed` slot so it\ntranslates across protocols (e.g. to a Gemini upstream's\n`generationConfig.seed`) instead of no-op'ing as a top-level key on a\nnested-config wire.\n<https://platform.openai.com/docs/api-reference/chat/create#chat-create-seed>","type":["integer","null"],"format":"int64","default":null},"stop":{"description":"Stop sequences — a single string or an array of up to four. Promoted to\nthe canonical `stop` slot.\n<https://platform.openai.com/docs/api-reference/chat/create#chat-create-stop>","default":null},"store":{"description":"Whether OpenAI may retain the request and response.","type":["boolean","null"],"default":null},"stream":{"type":"boolean","default":false},"stream_options":{"description":"Streaming response controls.","anyOf":[{"$ref":"#/$defs/ChatStreamOptions"},{"type":"null"}],"default":null},"temperature":{"type":["number","null"],"format":"double","default":null},"tools":{"type":"array","items":{"$ref":"#/$defs/ChatTool"}},"top_p":{"type":["number","null"],"format":"double","default":null}},"required":["model","messages"],"$defs":{"ChatFunctionCall":{"description":"The `function` payload of a [`ChatToolCall`]: name + raw JSON argument string.","type":"object","properties":{"arguments":{"type":"string","default":""},"name":{"type":"string","default":""}}},"ChatJsonSchema":{"description":"The `json_schema` payload of [`ChatResponseFormat::JsonSchema`].","type":"object","properties":{"description":{"description":"Optional schema description — extra LLM guidance OpenAI passes through to\nthe model. Promoted to the canonical `response_format` description.\n<https://platform.openai.com/docs/guides/structured-outputs>","type":["string","null"]},"name":{"description":"Schema name (OpenAI requires it).","type":"string"},"schema":{"description":"The JSON Schema."},"strict":{"description":"Strict-mode flag.","type":["boolean","null"]}},"required":["name","schema"]},"ChatMessage":{"description":"One element of [`ChatRequest`]'s `messages` array — a chat turn carrying\nrole + optional content + optional tool calls / tool-call reply id.","type":"object","properties":{"content":{"description":"`content` may be a plain string or an array of content parts, or absent\n(an assistant turn that is purely `tool_calls`).","default":null},"reasoning_content":{"description":"Reasoning content — **not** in OpenAI's Chat Completions spec; this is\na vendor extension used by DeepSeek\n(<https://api-docs.deepseek.com/api/create-chat-completion>), Moonshot\n(Kimi), Qwen, and other OpenAI-compatible providers that expose the\nmodel's chain-of-thought on the Chat envelope. v0 #454-1: it must\nnot be dropped. `parse_response` additionally accepts `reasoning`\n(some OpenRouter passthroughs) and `thinking` (Aliyun) as aliases.","type":["string","null"],"default":null},"role":{"type":"string"},"tool_call_id":{"type":["string","null"],"default":null},"tool_calls":{"type":"array","items":{"$ref":"#/$defs/ChatToolCall"}}},"required":["role"]},"ChatResponseFormat":{"description":"Chat Completions `response_format`\n(<https://platform.openai.com/docs/guides/structured-outputs>) — a closed\nunion over OpenAI's three output modes.","oneOf":[{"description":"Free-form text — the default.","type":"object","properties":{"type":{"type":"string","const":"text"}},"required":["type"]},{"description":"Legacy JSON mode: valid JSON with no schema.","type":"object","properties":{"type":{"type":"string","const":"json_object"}},"required":["type"]},{"description":"JSON constrained to a schema.","type":"object","properties":{"json_schema":{"description":"The schema spec.","$ref":"#/$defs/ChatJsonSchema"},"type":{"type":"string","const":"json_schema"}},"required":["type","json_schema"]}]},"ChatStreamOptions":{"description":"Chat Completions streaming request options.\n\nThese options belong to the Chat Completions wire rather than the\nprotocol-neutral streaming response. Keeping them typed prevents a Chat\nclient's top-level object from leaking into Messages, Responses, or Gemini\nrequests while preserving same-protocol extensions through [`Self::extra`].","type":"object","properties":{"include_obfuscation":{"description":"Ask OpenAI not to add obfuscation bytes to streaming deltas.","type":["boolean","null"]},"include_usage":{"description":"Ask the upstream to emit a final usage-only streaming chunk.","type":["boolean","null"]}}},"ChatTool":{"description":"One element of [`ChatRequest`]'s `tools` array — a `{ function: { … } }` envelope.","type":"object","properties":{"function":{"$ref":"#/$defs/ChatToolFunction"}}},"ChatToolCall":{"description":"One assistant tool-call entry on a [`ChatMessage`].","type":"object","properties":{"function":{"$ref":"#/$defs/ChatFunctionCall"},"id":{"type":"string"}},"required":["id"]},"ChatToolFunction":{"description":"The `function` payload of a [`ChatTool`]: name + description + JSON-Schema\nparameters + optional `strict` flag.\n<https://platform.openai.com/docs/guides/function-calling#strict-mode>","type":"object","properties":{"description":{"type":["string","null"],"default":null},"name":{"type":"string"},"parameters":{"default":null},"strict":{"description":"OpenAI strict-mode flag (V3 `strict`). Captured so it is not lost across\nthe canonical boundary.","type":["boolean","null"],"default":null}},"required":["name"]},"ReasoningEffort":{"description":"Qualitative reasoning-effort levels understood by BitRouter's built-in\nOpenAI, Anthropic, and Gemini protocol adapters.\n\nThis is the cross-provider superset, not a claim that every model supports\nevery value. Exact provider/model routes advertise their supported subset\nseparately and policy-owned effort targets are validated against it before\ndispatch.","oneOf":[{"description":"Disable reasoning where the selected model supports doing so.","type":"string","const":"none"},{"description":"Use the smallest non-zero reasoning setting exposed by the model.","type":"string","const":"minimal"},{"description":"Prefer low reasoning cost and latency.","type":"string","const":"low"},{"description":"Balance reasoning depth with cost and latency.","type":"string","const":"medium"},{"description":"Prefer deeper reasoning over cost and latency.","type":"string","const":"high"},{"description":"Use the provider's extra-high reasoning setting.","type":"string","const":"xhigh"},{"description":"Use the provider's maximum reasoning setting.","type":"string","const":"max"}]}}}}},"required":true},"responses":{"200":{"description":"Chat completion response (non-streaming).\n\nStreamed chat completion — Server-Sent Events with one `ChatCompletionChunk` per `data:` line, terminated by `data: [DONE]`.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ChatCompletionResponseDoc","description":"MIRROR: `bitrouter_sdk::language_model::protocol::chat_completions` response","type":"object","properties":{"choices":{"type":"array","items":{"$ref":"#/$defs/ChatCompletionChoiceDoc"}},"created":{"description":"Unix timestamp (seconds) of when the completion was created.","type":"integer","format":"uint64","minimum":0},"id":{"description":"A unique identifier for the completion.","type":"string"},"model":{"description":"The model used for the completion.","type":"string"},"object":{"description":"Object type — always `chat.completion`.","type":"string"},"usage":{"anyOf":[{"$ref":"#/$defs/ChatCompletionUsageDoc"},{"type":"null"}]}},"required":["id","object","created","model","choices"],"$defs":{"ChatCompletionChoiceDoc":{"type":"object","properties":{"finish_reason":{"type":["string","null"]},"index":{"type":"integer","format":"uint32","minimum":0},"message":{"$ref":"#/$defs/ChatCompletionMessageDoc"}},"required":["index","message"]},"ChatCompletionMessageDoc":{"type":"object","properties":{"content":{"type":["string","null"]},"role":{"type":"string"}},"required":["role"]},"ChatCompletionUsageDoc":{"type":"object","properties":{"completion_tokens":{"type":"integer","format":"uint32","minimum":0},"prompt_tokens":{"type":"integer","format":"uint32","minimum":0},"total_tokens":{"type":"integer","format":"uint32","minimum":0}},"required":["prompt_tokens","completion_tokens","total_tokens"]}}}},"text/event-stream":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ChatCompletionChunkDoc","description":"MIRROR: a single SSE `data:` payload in the streaming `/v1/chat/completions`\nresponse. Used to type the `text/event-stream` content for the same route.","type":"object","properties":{"choices":{"type":"array","items":{"$ref":"#/$defs/ChatCompletionChunkChoiceDoc"}},"created":{"type":"integer","format":"uint64","minimum":0},"id":{"type":"string"},"model":{"type":"string"},"object":{"type":"string"},"usage":{"anyOf":[{"$ref":"#/$defs/ChatCompletionUsageDoc"},{"type":"null"}]}},"required":["id","object","created","model","choices"],"$defs":{"ChatCompletionChunkChoiceDoc":{"type":"object","properties":{"delta":{"$ref":"#/$defs/ChatCompletionChunkDeltaDoc"},"finish_reason":{"type":["string","null"]},"index":{"type":"integer","format":"uint32","minimum":0}},"required":["index","delta"]},"ChatCompletionChunkDeltaDoc":{"type":"object","properties":{"content":{"type":["string","null"]},"role":{"type":["string","null"]}}},"ChatCompletionUsageDoc":{"type":"object","properties":{"completion_tokens":{"type":"integer","format":"uint32","minimum":0},"prompt_tokens":{"type":"integer","format":"uint32","minimum":0},"total_tokens":{"type":"integer","format":"uint32","minimum":0}},"required":["prompt_tokens","completion_tokens","total_tokens"]}}}}}},"400":{"description":"Bad request — invalid model or malformed request body.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"402":{"description":"Payment required — insufficient balance or missing payment proof.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"404":{"description":"No route found for the requested model.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"429":{"description":"Rate limited by BitRouter or by every usable upstream route. Inspect error.code to distinguish rate_limit_exceeded from upstream_rate_limited; Retry-After is included when known.","headers":{"Retry-After":{"description":"Seconds until the earliest upstream route may be retried, when known.","style":"simple","schema":{"type":"string"}},"x-bitrouter-error-source":{"description":"Set to `upstream` when every usable upstream route was rate limited.","style":"simple","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"500":{"description":"BitRouter internal error.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"502":{"description":"Upstream returned an invalid response.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"503":{"description":"The usable upstream route set is temporarily unavailable.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"504":{"description":"Every usable upstream route timed out.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/responses":{"post":{"tags":["OpenAI Responses"],"summary":"Create response","description":"Creates a response using the OpenAI Responses API format. Drop-in replacement for OpenAI's newer stateful-conversation surface.\n\nWhen `stream: true`, the response is sent as Server-Sent Events (SSE) with the full output-item lifecycle (`response.created`, `response.output_item.added`, `response.output_text.delta`, `response.completed`, …). The cloud forwards the upstream provider's SSE stream unchanged.","operationId":"createResponse","requestBody":{"description":"OpenAI Responses API request.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ResponsesRequest","description":"Responses request body\n(<https://platform.openai.com/docs/api-reference/responses/create>).\n\n`pub` so downstream crates (notably `bitrouter-cloud`) can derive an\nOpenAPI schema from the canonical wire shape without redeclaring it.\n\n`input` stays `serde_json::Value` on purpose — the Responses API accepts\neither a plain string or a heterogeneous item array (Codex multi-turn,\n#454-3), and the deeper walk happens in `parse_input` (private). Mirrors\nhow Anthropic's `system` / `content` are typed.","type":"object","properties":{"input":true,"instructions":{"type":["string","null"],"default":null},"max_output_tokens":{"type":["integer","null"],"format":"uint32","default":null,"minimum":0},"model":{"type":"string","default":""},"parallel_tool_calls":{"description":"Whether the model may issue tool calls in parallel.","type":["boolean","null"],"default":null},"reasoning":{"anyOf":[{"$ref":"#/$defs/ResponsesReasoningConfig"},{"type":"null"}]},"store":{"description":"Whether OpenAI may retain the request and response.","type":["boolean","null"],"default":null},"stream":{"type":"boolean","default":false},"temperature":{"type":["number","null"],"format":"double","default":null},"text":{"description":"Output `text` config — `format` is the structured-output constraint\n(`json_schema` is promoted to the canonical slot; `text` / `json_object`\npass through). Sibling keys (e.g. `verbosity`) survive via `extra`.","anyOf":[{"$ref":"#/$defs/ResponsesText"},{"type":"null"}]},"tools":{"type":"array","items":{"$ref":"#/$defs/ResponsesTool"}},"top_p":{"type":["number","null"],"format":"double","default":null}},"required":["input"],"$defs":{"ReasoningEffort":{"description":"Qualitative reasoning-effort levels understood by BitRouter's built-in\nOpenAI, Anthropic, and Gemini protocol adapters.\n\nThis is the cross-provider superset, not a claim that every model supports\nevery value. Exact provider/model routes advertise their supported subset\nseparately and policy-owned effort targets are validated against it before\ndispatch.","oneOf":[{"description":"Disable reasoning where the selected model supports doing so.","type":"string","const":"none"},{"description":"Use the smallest non-zero reasoning setting exposed by the model.","type":"string","const":"minimal"},{"description":"Prefer low reasoning cost and latency.","type":"string","const":"low"},{"description":"Balance reasoning depth with cost and latency.","type":"string","const":"medium"},{"description":"Prefer deeper reasoning over cost and latency.","type":"string","const":"high"},{"description":"Use the provider's extra-high reasoning setting.","type":"string","const":"xhigh"},{"description":"Use the provider's maximum reasoning setting.","type":"string","const":"max"}]},"ResponsesReasoningConfig":{"description":"`reasoning` knob on [`ResponsesRequest`]. `effort` is promoted to the\ncanonical slot; sibling fields such as `summary` round-trip via `extra`.","type":"object","properties":{"effort":{"anyOf":[{"$ref":"#/$defs/ReasoningEffort"},{"type":"null"}],"default":null}}},"ResponsesText":{"description":"Responses `text` config. `format` constrains output shape; sibling keys\n(e.g. `verbosity`) pass through via `extra`.","type":"object","properties":{"format":{"anyOf":[{"$ref":"#/$defs/ResponsesTextFormat"},{"type":"null"}],"default":null}}},"ResponsesTextFormat":{"description":"Responses `text.format`\n(<https://platform.openai.com/docs/api-reference/responses/create>) — a\nclosed union over OpenAI's three output modes.","oneOf":[{"description":"Free-form text — the default.","type":"object","properties":{"type":{"type":"string","const":"text"}},"required":["type"]},{"description":"Legacy JSON mode.","type":"object","properties":{"type":{"type":"string","const":"json_object"}},"required":["type"]},{"description":"JSON constrained to a schema.","type":"object","properties":{"description":{"description":"Optional schema description — extra LLM guidance OpenAI passes to the\nmodel. Promoted to the canonical `response_format` description.\n<https://platform.openai.com/docs/api-reference/responses/create>","type":["string","null"]},"name":{"description":"Schema name (OpenAI requires it).","type":"string"},"schema":{"description":"The JSON Schema."},"strict":{"description":"Strict-mode flag.","type":["boolean","null"]},"type":{"type":"string","const":"json_schema"}},"required":["type","name","schema"]}]},"ResponsesTool":{"description":"One element of [`ResponsesRequest`]'s `tools` array.\n\nResponses uses one flat array for both kinds of tool:\n- a **function** tool — `{type:\"function\", name, description?, parameters, strict?}`;\n- a **provider-defined** server tool — `{type:\"web_search_preview\"|…, …config}`\n  (`code_interpreter`, `file_search`, `image_generation`, `computer_use_preview`).\n\n`kind` (`type`) discriminates the two; for a server tool the configuration\nkeys ride in `extra` so they are preserved verbatim into the canonical\n`Tool::ProviderDefined.args`.\n<https://platform.openai.com/docs/api-reference/responses/create#responses-create-tools>","type":"object","properties":{"description":{"type":["string","null"],"default":null},"name":{"type":["string","null"],"default":null},"parameters":{"default":null},"strict":{"description":"OpenAI strict-mode flag (V3 `strict`) on a function tool. Captured so it\nis not lost across the canonical boundary.","type":["boolean","null"],"default":null},"type":{"type":["string","null"],"default":null}}}}}}},"required":true},"responses":{"200":{"description":"Response object (non-streaming).\n\nStreamed Responses output — Server-Sent Events with the full output-item lifecycle (`response.created`, `response.output_item.added`, `response.completed`, …).","content":{"application/json":{"schema":{"description":"OpenAI Responses API response envelope. Refer to OpenAI's published Responses spec for the full field set; bitrouter forwards the upstream body unchanged.","type":"object"}},"text/event-stream":{"schema":{"description":"A single Responses SSE event. The `type` field discriminates the lifecycle stage.","type":"object"}}}},"400":{"description":"Bad request — invalid model or malformed request body.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"402":{"description":"Payment required — insufficient balance or missing payment proof.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"404":{"description":"No route found for the requested model.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"429":{"description":"Rate limited by BitRouter or by every usable upstream route. Inspect error.code to distinguish rate_limit_exceeded from upstream_rate_limited; Retry-After is included when known.","headers":{"Retry-After":{"description":"Seconds until the earliest upstream route may be retried, when known.","style":"simple","schema":{"type":"string"}},"x-bitrouter-error-source":{"description":"Set to `upstream` when every usable upstream route was rate limited.","style":"simple","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"500":{"description":"BitRouter internal error.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"502":{"description":"Upstream returned an invalid response.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"503":{"description":"The usable upstream route set is temporarily unavailable.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"504":{"description":"Every usable upstream route timed out.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1/messages":{"post":{"tags":["Anthropic Compatible"],"summary":"Create message","description":"Creates a message using the Anthropic Messages API format. Drop-in replacement for the Anthropic API.\n\nWhen `stream: true`, the response is sent as Server-Sent Events (SSE). Each event has a `type` field indicating the event kind (`message_start`, `content_block_delta`, `message_delta`, `message_stop`).","operationId":"createMessage","requestBody":{"description":"Anthropic Messages request.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"MessagesRequest","description":"Messages request body (<https://docs.anthropic.com/en/api/messages>).\n\n`pub` so downstream crates (notably `bitrouter-cloud`) can derive an\nOpenAPI schema from the canonical wire shape without redeclaring it.","type":"object","properties":{"max_tokens":{"type":["integer","null"],"format":"uint32","default":null,"minimum":0},"messages":{"type":"array","items":{"$ref":"#/$defs/MessagesMessage"}},"model":{"type":"string"},"output_config":{"description":"Structured-output + reasoning config — `format` (`json_schema`) is\npromoted to the canonical `response_format` and `effort` to the canonical\nreasoning effort. Sibling keys pass through via `extra`.\n<https://platform.claude.com/docs/en/build-with-claude/structured-outputs>","anyOf":[{"$ref":"#/$defs/MessagesOutputConfig"},{"type":"null"}]},"stop_sequences":{"description":"Custom stop sequences. Promoted to the canonical `stop` slot, so it can\nrender as a Chat Completions `stop` or a Gemini `stopSequences`.\n<https://docs.anthropic.com/en/api/messages#body-stop-sequences>","type":["array","null"],"default":null,"items":{"type":"string"}},"stream":{"type":"boolean","default":false},"system":{"description":"String or an array of `{type:\"text\", text}` blocks (#227 → #228).","default":null},"temperature":{"type":["number","null"],"format":"double","default":null},"tools":{"type":"array","items":{"$ref":"#/$defs/MessagesTool"}},"top_k":{"description":"Top-k sampling. Promoted to the canonical `top_k` slot so it translates\nacross protocols (e.g. to a Gemini upstream's `generationConfig.topK`).\n<https://docs.anthropic.com/en/api/messages#body-top-k>","type":["integer","null"],"format":"uint32","default":null,"minimum":0},"top_p":{"type":["number","null"],"format":"double","default":null}},"required":["model","messages"],"$defs":{"MessagesMessage":{"description":"One element of [`MessagesRequest`]'s `messages` array — a `{ role, content }` turn.","type":"object","properties":{"content":{"description":"String or an array of content blocks."},"role":{"type":"string"}},"required":["role","content"]},"MessagesOutputConfig":{"description":"Messages `output_config` — structured output + reasoning effort.","type":"object","properties":{"effort":{"description":"Reasoning effort (`low` | `medium` | `high` | `xhigh` | `max`).","anyOf":[{"$ref":"#/$defs/ReasoningEffort"},{"type":"null"}],"default":null},"format":{"anyOf":[{"$ref":"#/$defs/MessagesOutputFormat"},{"type":"null"}]}}},"MessagesOutputFormat":{"description":"Messages `output_config.format`\n(<https://platform.claude.com/docs/en/build-with-claude/structured-outputs>).\nAnthropic's GA structured-output format carries no name / strict.","oneOf":[{"description":"JSON constrained to a schema.","type":"object","properties":{"schema":{"description":"The JSON Schema."},"type":{"type":"string","const":"json_schema"}},"required":["type","schema"]}]},"MessagesTool":{"description":"One element of [`MessagesRequest`]'s `tools` array.\n\nAnthropic uses one array for both kinds of tool:\n- a **client (function) tool** — `{name, description?, input_schema}` (no `type`);\n- a **provider-defined (server) tool** — `{type:\"web_search_20250305\"|…, name, …config}`\n  (web search, code execution, computer use, bash, text editor), where `type`\n  is the dated tool version and `name` is the stable tool name.\n\nA versioned `type` discriminates a server tool; its config keys ride in\n`extra` so they are preserved verbatim into `Tool::ProviderDefined.args`.\n<https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview>\n<https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool>","type":"object","properties":{"description":{"type":["string","null"],"default":null},"input_schema":{"default":null},"name":{"type":["string","null"],"default":null},"type":{"type":["string","null"],"default":null}}},"ReasoningEffort":{"description":"Qualitative reasoning-effort levels understood by BitRouter's built-in\nOpenAI, Anthropic, and Gemini protocol adapters.\n\nThis is the cross-provider superset, not a claim that every model supports\nevery value. Exact provider/model routes advertise their supported subset\nseparately and policy-owned effort targets are validated against it before\ndispatch.","oneOf":[{"description":"Disable reasoning where the selected model supports doing so.","type":"string","const":"none"},{"description":"Use the smallest non-zero reasoning setting exposed by the model.","type":"string","const":"minimal"},{"description":"Prefer low reasoning cost and latency.","type":"string","const":"low"},{"description":"Balance reasoning depth with cost and latency.","type":"string","const":"medium"},{"description":"Prefer deeper reasoning over cost and latency.","type":"string","const":"high"},{"description":"Use the provider's extra-high reasoning setting.","type":"string","const":"xhigh"},{"description":"Use the provider's maximum reasoning setting.","type":"string","const":"max"}]}}}}},"required":true},"responses":{"200":{"description":"Messages response (non-streaming).\n\nStreamed Messages response — Server-Sent Events. Each event has a `type` field (`message_start`, `content_block_delta`, …).","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"MessagesResponseDoc","description":"MIRROR: `bitrouter_sdk::language_model::protocol::messages` response","type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/$defs/MessagesContentBlockDoc"}},"id":{"type":"string"},"model":{"type":"string"},"role":{"description":"Always `assistant`.","type":"string"},"stop_reason":{"type":["string","null"]},"stop_sequence":{"type":["string","null"]},"type":{"description":"Always `message`.","type":"string"},"usage":{"$ref":"#/$defs/MessagesUsageDoc"}},"required":["id","type","role","content","model","usage"],"$defs":{"MessagesContentBlockDoc":{"type":"object","properties":{"text":{"type":"string"},"type":{"description":"Block type — `text` is the only variant emitted today.","type":"string"}},"required":["type","text"]},"MessagesUsageDoc":{"type":"object","properties":{"cache_creation_input_tokens":{"description":"Number of tokens written to the prompt cache by this request. Present\n(non-zero) only when the request enabled prompt caching.","type":["integer","null"],"format":"uint32","minimum":0},"cache_read_input_tokens":{"description":"Number of tokens read from the prompt cache by this request. Present\n(non-zero) only when the request reused a cached prompt.","type":["integer","null"],"format":"uint32","minimum":0},"input_tokens":{"type":"integer","format":"uint32","minimum":0},"output_tokens":{"type":"integer","format":"uint32","minimum":0}},"required":["input_tokens","output_tokens"]}}}},"text/event-stream":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"MessagesStreamEventDoc","description":"MIRROR: a single SSE event in the streaming `/v1/messages` response.","type":"object","properties":{"delta":{"anyOf":[{"$ref":"#/$defs/MessagesStreamDeltaDoc"},{"type":"null"}]},"index":{"type":["integer","null"],"format":"uint32","minimum":0},"message":{"anyOf":[{"$ref":"#/$defs/MessagesStreamMessageDoc"},{"type":"null"}]},"type":{"description":"Event type — `message_start`, `content_block_delta`, `message_delta`,\n`message_stop`, etc.","type":"string"}},"required":["type"],"$defs":{"MessagesStreamDeltaDoc":{"type":"object","properties":{"stop_reason":{"type":["string","null"]},"text":{"type":["string","null"]},"type":{"type":["string","null"]}}},"MessagesStreamMessageDoc":{"type":"object","properties":{"id":{"type":"string"},"model":{"type":"string"},"role":{"type":"string"}},"required":["id","model","role"]}}}}}},"400":{"description":"Bad request — invalid model or malformed request body.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"402":{"description":"Payment required — insufficient balance or missing payment proof.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"404":{"description":"No route found for the requested model.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"429":{"description":"Rate limited by BitRouter or by every usable upstream route. Inspect error.code to distinguish rate_limit_exceeded from upstream_rate_limited; Retry-After is included when known.","headers":{"Retry-After":{"description":"Seconds until the earliest upstream route may be retried, when known.","style":"simple","schema":{"type":"string"}},"x-bitrouter-error-source":{"description":"Set to `upstream` when every usable upstream route was rate limited.","style":"simple","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"500":{"description":"BitRouter internal error.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"502":{"description":"Upstream returned an invalid response.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"503":{"description":"The usable upstream route set is temporarily unavailable.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"504":{"description":"Every usable upstream route timed out.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/v1beta/models/{model_action}":{"post":{"tags":["Google Compatible"],"summary":"Generate content (Google)","description":"Generates content using the Google Generative Language API format. Drop-in replacement for `generativelanguage.googleapis.com/v1beta`.\n\nThe model id and streaming verb are both encoded in the `model_action` path segment — for example `gemini-2.0-flash:generateContent` (synchronous) or `gemini-2.0-flash:streamGenerateContent` (SSE). The cloud injects the model id into the request body before dispatching, so callers can use the same URL convention as Google's own API.","operationId":"googleGenerateContent","parameters":[{"in":"path","name":"model_action","description":"`{model}:{action}` segment — Google encodes both the model id and the streaming verb in one path component. `action` is either `generateContent` (synchronous) or `streamGenerateContent` (SSE). Example: `gemini-2.0-flash:generateContent`.","required":true,"schema":{"type":"string"},"style":"simple"}],"requestBody":{"description":"Google Generative Language `:generateContent` request.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"GenerateContentRequest","description":"Generate Content `generateContent` request body\n(<https://ai.google.dev/api/generate-content>).\n\n`pub` so downstream crates (notably `bitrouter-cloud`) can derive an\nOpenAPI schema from the canonical wire shape without redeclaring it.","type":"object","properties":{"contents":{"type":"array","items":{"$ref":"#/$defs/GenerateContentContent"}},"generationConfig":{"anyOf":[{"$ref":"#/$defs/GenerateContentGenerationConfig"},{"type":"null"}]},"model":{"description":"Carried as a field so the inbound HTTP route's `{model}` path param can\noverride it; defaults empty.","type":"string","default":""},"stream":{"description":"Injected by `server::generate_content` from the path verb\n(`:streamGenerateContent` → true, `:generateContent` → false).","type":"boolean","default":false},"systemInstruction":{"anyOf":[{"$ref":"#/$defs/GenerateContentContent"},{"type":"null"}]},"tools":{"type":"array","items":{"$ref":"#/$defs/GenerateContentTool"}}},"required":["contents"],"$defs":{"GenerateContentContent":{"description":"One element of [`GenerateContentRequest`]'s `contents` array — a turn\ncarrying optional role + `parts[]`.","type":"object","properties":{"parts":{"type":"array","default":[],"items":true},"role":{"type":["string","null"],"default":null}}},"GenerateContentFunctionDecl":{"description":"One function declaration inside a [`GenerateContentTool`]: name + description +\nJSON-Schema parameters.","type":"object","properties":{"description":{"type":["string","null"],"default":null},"name":{"type":"string"},"parameters":{"default":null}},"required":["name"]},"GenerateContentGenerationConfig":{"description":"`generationConfig` knobs on a [`GenerateContentRequest`].","type":"object","properties":{"frequencyPenalty":{"description":"Frequency penalty. Promoted to the canonical `frequency_penalty` slot.\n<https://ai.google.dev/api/generate-content#GenerationConfig>","type":["number","null"],"format":"double","default":null},"maxOutputTokens":{"type":["integer","null"],"format":"uint32","default":null,"minimum":0},"presencePenalty":{"description":"Presence penalty. Promoted to the canonical `presence_penalty` slot.\n<https://ai.google.dev/api/generate-content#GenerationConfig>","type":["number","null"],"format":"double","default":null},"responseMimeType":{"description":"Response MIME type. `application/json` paired with `response_schema` is\nthe structured-output contract; other values (e.g. `text/x.enum`) pass\nthrough opaquely.\n<https://ai.google.dev/gemini-api/docs/structured-output>","type":["string","null"],"default":null},"responseSchema":{"description":"JSON Schema constraining the response (with\n`response_mime_type: \"application/json\"`).","default":null},"seed":{"description":"Deterministic-sampling seed. Promoted to the canonical `seed` slot.\n<https://ai.google.dev/api/generate-content#GenerationConfig>","type":["integer","null"],"format":"int64","default":null},"stopSequences":{"description":"Stop sequences. Promoted to the canonical `stop` slot, so it can render\nas a Chat Completions `stop` or an Anthropic `stop_sequences`.\n<https://ai.google.dev/api/generate-content#GenerationConfig>","type":["array","null"],"default":null,"items":{"type":"string"}},"temperature":{"type":["number","null"],"format":"double","default":null},"thinkingConfig":{"description":"Qualitative reasoning effort for Gemini 3+ models. Numeric\n`thinkingBudget` remains an opaque sibling because it is a distinct\nGemini 2.5 control with no lossless qualitative mapping.","anyOf":[{"$ref":"#/$defs/GenerateContentThinkingConfig"},{"type":"null"}]},"topK":{"description":"Top-k sampling. Promoted to the canonical `top_k` slot so it translates\nacross protocols (e.g. to an Anthropic upstream's `top_k`).\n<https://ai.google.dev/api/generate-content#GenerationConfig>","type":["integer","null"],"format":"uint32","default":null,"minimum":0},"topP":{"type":["number","null"],"format":"double","default":null}}},"GenerateContentThinkingConfig":{"description":"Gemini `generationConfig.thinkingConfig`.","type":"object","properties":{"thinkingLevel":{"anyOf":[{"$ref":"#/$defs/ReasoningEffort"},{"type":"null"}],"default":null}}},"GenerateContentTool":{"description":"One element of [`GenerateContentRequest`]'s `tools` array.\n\nA single Google tool object may carry client function declarations\n(`functionDeclarations`) **and/or** one or more provider-defined (\"built-in\")\ntool keys on the same object — `googleSearch`, `codeExecution`,\n`googleSearchRetrieval`, `urlContext`. Function declarations parse to\n[`Tool::Function`]; every other key is a provider-defined tool namespaced\n`google.<key>`, its value preserved verbatim as `args`. The non-function keys\nride in `extra`.\n<https://ai.google.dev/gemini-api/docs/function-calling>\n<https://ai.google.dev/gemini-api/docs/google-search>\n<https://ai.google.dev/gemini-api/docs/code-execution>","type":"object","properties":{"functionDeclarations":{"type":"array","items":{"$ref":"#/$defs/GenerateContentFunctionDecl"}}}},"ReasoningEffort":{"description":"Qualitative reasoning-effort levels understood by BitRouter's built-in\nOpenAI, Anthropic, and Gemini protocol adapters.\n\nThis is the cross-provider superset, not a claim that every model supports\nevery value. Exact provider/model routes advertise their supported subset\nseparately and policy-owned effort targets are validated against it before\ndispatch.","oneOf":[{"description":"Disable reasoning where the selected model supports doing so.","type":"string","const":"none"},{"description":"Use the smallest non-zero reasoning setting exposed by the model.","type":"string","const":"minimal"},{"description":"Prefer low reasoning cost and latency.","type":"string","const":"low"},{"description":"Balance reasoning depth with cost and latency.","type":"string","const":"medium"},{"description":"Prefer deeper reasoning over cost and latency.","type":"string","const":"high"},{"description":"Use the provider's extra-high reasoning setting.","type":"string","const":"xhigh"},{"description":"Use the provider's maximum reasoning setting.","type":"string","const":"max"}]}}}}},"required":true},"responses":{"200":{"description":"Generated content (non-streaming).\n\nStreamed generation — Server-Sent Events, one JSON object per `data:` line. Use the `:streamGenerateContent` action to opt in.","content":{"application/json":{"schema":{"description":"Google Generative Language response envelope. Refer to Google's published spec for the full field set; bitrouter forwards the upstream body unchanged.","type":"object"}},"text/event-stream":{"schema":{"description":"A single Google streaming chunk.","type":"object"}}}},"400":{"description":"Bad request — invalid model or malformed request body.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"402":{"description":"Payment required — insufficient balance or missing payment proof.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"404":{"description":"No route found for the requested model.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"429":{"description":"Rate limited by BitRouter or by every usable upstream route. Inspect error.code to distinguish rate_limit_exceeded from upstream_rate_limited; Retry-After is included when known.","headers":{"Retry-After":{"description":"Seconds until the earliest upstream route may be retried, when known.","style":"simple","schema":{"type":"string"}},"x-bitrouter-error-source":{"description":"Set to `upstream` when every usable upstream route was rate limited.","style":"simple","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"500":{"description":"BitRouter internal error.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"502":{"description":"Upstream returned an invalid response.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"503":{"description":"The usable upstream route set is temporarily unavailable.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}},"504":{"description":"Every usable upstream route timed out.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"ErrorResponseDoc","description":"MIRROR: the JSON shape `bitrouter_sdk::error::BitrouterError` serialises into\n(`{ \"error\": { \"code\": ..., \"message\": ..., \"type\": ... } }`). Cloud handlers map to\nthis envelope via `BitrouterError::into_response`.","type":"object","properties":{"error":{"$ref":"#/$defs/ErrorBodyDoc"}},"required":["error"],"$defs":{"ErrorBodyDoc":{"type":"object","properties":{"code":{"description":"Stable machine-readable error code (e.g. `upstream_rate_limited`).","type":"string"},"message":{"description":"Human-readable error description.","type":"string"},"type":{"description":"Broad OpenAI-compatible error category (e.g. `rate_limit_error`).","type":"string"}},"required":["code","message","type"]}}}}}}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}}},"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Anthropic-style API key header."},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key or JWT","description":"`Authorization: Bearer <token>` where `<token>` is either an API key issued by the BitRouter console or a JWT minted from a wallet (CAIP-10 issuer)."}}},"tags":[{"name":"OpenAI Compatible","description":"OpenAI Chat Completions format. Drop-in compatible with the OpenAI Chat Completions API — accepts the same request schema and returns the same response format."},{"name":"OpenAI Responses","description":"OpenAI Responses API format. Newer stateful-conversation surface; distinct request/response shape from `/v1/chat/completions`."},{"name":"Anthropic Compatible","description":"Anthropic-format endpoints. Drop-in compatible with the Anthropic Messages API."},{"name":"Google Compatible","description":"Google Generative Language API format. The URL encodes the model and streaming verb in a single segment (`models/{model}:generateContent` or `:streamGenerateContent`) — same convention as Google's own API."},{"name":"Discovery","description":"Public read-only endpoints for inspecting the router's configuration — what models and providers it knows about."},{"name":"BYOK","description":"Bring-Your-Own-Key endpoints. Returns the node's sealed-box public key so the console can encrypt provider keys client-side; the node never sees plaintext on the write path."},{"name":"Observability","description":"Operational metrics for scrapers. Not intended for human callers — Prometheus-format text exposition."},{"name":"Health","description":"Liveness check."},{"name":"Management","description":"Account-bound management endpoints — API keys, usage, billing, policies, BYOK provider keys, OAuth clients. Every endpoint requires a credential whose principal carries the per-endpoint scope (e.g. `keys:read`, `billing:write`)."}]}