{ "openapi": "3.1.0", "info": { "title": "App AI Gateway API", "version": "0.1.0", "description": "A provider-native AI proxy for iOS applications and trusted server backends. Provider keys stay on the gateway; requests are checked, limited and recorded before they reach a provider." }, "servers": [ { "url": "https://api.appaigateway.com", "description": "The cloud API host. On a self-hosted gateway, use your own origin." } ], "tags": [ { "name": "CLI", "description": "CLI discovery, protected initialization and human browser handoffs." }, { "name": "Operations", "description": "Unauthenticated service health." }, { "name": "Console authentication", "description": "Sign-up, sign-in and session lifecycle for the console." }, { "name": "Application authentication", "description": "Issuer identity plus App Attest or API-key client proof." }, { "name": "Application", "description": "Authenticated application-user state." }, { "name": "Provider proxy", "description": "Provider-native streaming proxy endpoints." }, { "name": "Named endpoints", "description": "Server-configured provider and model behind a stable slug." }, { "name": "Admin applications", "description": "Application configuration lifecycle." }, { "name": "Admin operations", "description": "Keys, users, and usage." }, { "name": "Admin management keys", "description": "agw_mgmt_ credentials for scripts, CI and agents. They never expire, and are created and revoked from the console only." }, { "name": "Admin providers", "description": "Named provider instances and their credentials." }, { "name": "Admin provider gateways", "description": "Reusable Cloudflare AI Gateway connections shared by provider instances." }, { "name": "Admin organizations", "description": "Caller identity and organization switching." }, { "name": "Admin billing", "description": "Optional billing service-binding operations." }, { "name": "Admin models", "description": "Model pricing metadata." } ], "components": { "securitySchemes": { "ManagementBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "agw_mgmt_…", "description": "A management API key. It acts with its owning identity's current role for one account." }, "ConsoleSession": { "type": "apiKey", "in": "cookie", "name": "agw_identity_auth.session_token", "description": "The console's session cookie. Admin requests from the console also send x-console-request: 1." }, "CliPollProof": { "type": "http", "scheme": "bearer", "description": "The initiating CLI's private pollToken, distinct from the browser submission proof." }, "GatewayBearer": { "type": "http", "scheme": "bearer", "description": "A gateway access token, or an application API key for an issuer-less API-key app." } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Machine-readable facts about this rejection, present only where the code alone is not actionable. A billing_request_quota_exceeded rejection carries periodId, periodStart, periodEnd, limit, used, and resetAt; a billing_plan_limit_reached rejection carries limit and used; an app_rate_limited or app_budget_exhausted rejection carries scope, either user or app; a rate_limited rejection carries scope naming the endpoint policy that refused, plus limit, windowSeconds, retryAfterSeconds and resetAt." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "AppAttestRegisterRequest": { "type": "object", "properties": { "issuer_token": { "type": "string", "minLength": 1 }, "key_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "attestation": { "type": "string", "minLength": 1 }, "challenge": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "key_id", "attestation", "challenge" ] }, "AppAttestTokenRequest": { "type": "object", "properties": { "issuer_token": { "type": "string", "minLength": 1 }, "key_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "assertion": { "type": "string", "minLength": 1 }, "challenge": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "key_id", "assertion", "challenge" ] }, "ApiKeyTokenRequest": { "type": "object", "properties": { "issuer_token": { "type": "string", "minLength": 1 }, "api_key": { "type": "string", "minLength": 1 } }, "required": [ "issuer_token", "api_key" ], "additionalProperties": false }, "AppConfig": { "type": "object", "properties": { "authentication": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "apple_app_attest" ] }, "end_user": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "issuer" ] }, "issuer": { "type": "object", "properties": { "jwks_url": { "type": "string", "format": "uri" }, "issuer": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] }, "audience": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] }, "user_id_claim": { "type": "string" }, "token_header": { "type": "string" }, "required_claims": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "contains": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ] }, "equals": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "path" ] } }, "max_token_lifetime_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "provider": { "type": "string", "enum": [ "firebase", "supabase", "auth0", "clerk", "custom" ] }, "entitlement": { "type": "string", "enum": [ "revenuecat", "custom" ] } }, "required": [ "jwks_url", "issuer", "audience", "user_id_claim", "required_claims", "max_token_lifetime_seconds" ], "additionalProperties": false } }, "required": [ "source", "issuer" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "app_install" ] } }, "required": [ "source" ], "additionalProperties": false } ] }, "app_attest": { "type": "object", "properties": { "team_id": { "type": "string" }, "bundle_id": { "type": "string" }, "environments": { "type": "array", "items": { "type": "string", "enum": [ "production", "development" ] }, "minItems": 1 } }, "required": [ "team_id", "bundle_id" ], "additionalProperties": false } }, "required": [ "type", "end_user", "app_attest" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "api_key" ] }, "end_user": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "header" ] }, "header": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9!#$%&'*+.^_`|~-]+$" } }, "required": [ "source", "header" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "issuer" ] }, "issuer": { "type": "object", "properties": { "jwks_url": { "type": "string", "format": "uri" }, "issuer": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] }, "audience": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] }, "user_id_claim": { "type": "string" }, "token_header": { "type": "string" }, "required_claims": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "contains": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ] }, "equals": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "path" ] } }, "max_token_lifetime_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "provider": { "type": "string", "enum": [ "firebase", "supabase", "auth0", "clerk", "custom" ] }, "entitlement": { "type": "string", "enum": [ "revenuecat", "custom" ] } }, "required": [ "jwks_url", "issuer", "audience", "user_id_claim", "required_claims", "max_token_lifetime_seconds" ], "additionalProperties": false } }, "required": [ "source", "issuer" ], "additionalProperties": false } ] } }, "required": [ "type" ], "additionalProperties": false } ] }, "routing": { "type": "object", "properties": { "providers": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all", "selected" ] }, "selected": { "type": "object", "additionalProperties": { "type": "object", "properties": { "allowed_paths": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "path": { "type": "string" }, "fixed_model": { "type": "string" }, "clamp": { "type": "string", "enum": [ "responses", "chat_completions", "gemini_native", "anthropic", "none" ] } }, "required": [ "path" ] } ] } }, "allowed_models": { "type": "array", "items": { "type": "string" } }, "max_output_tokens": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "allowed_paths", "allowed_models" ] } } }, "required": [ "mode" ] }, "model_rewrites": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "providers", "model_rewrites" ] }, "limits": { "type": "object", "properties": { "per_user": { "type": "object", "properties": { "requests": { "type": "object", "properties": { "per_minute": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "per_day": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 } }, "required": [ "per_minute", "per_day" ] }, "spending": { "type": "object", "properties": { "monthly_usd": { "type": [ "number", "null" ], "minimum": 0 } }, "required": [ "monthly_usd" ] } }, "required": [ "requests", "spending" ] }, "per_app": { "type": "object", "properties": { "requests": { "type": "object", "properties": { "per_minute": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "per_day": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 } }, "required": [ "per_minute", "per_day" ] }, "spending": { "type": "object", "properties": { "monthly_usd": { "type": [ "number", "null" ], "minimum": 0 } }, "required": [ "monthly_usd" ] } }, "required": [ "requests", "spending" ] } }, "required": [ "per_user", "per_app" ] }, "endpoints": { "type": "object", "additionalProperties": { "type": "object", "properties": { "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,62}$" }, "model": { "type": "string", "minLength": 1 }, "api_style": { "type": "string", "enum": [ "responses", "transcription" ] }, "params": { "type": "object", "additionalProperties": {} }, "max_output_tokens": { "type": "integer", "exclusiveMinimum": 0 }, "fallback": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,62}$" }, "model": { "type": "string", "minLength": 1 } }, "required": [ "provider", "model" ] } } }, "required": [ "provider", "model", "api_style" ] } } }, "required": [ "authentication", "routing" ] }, "AppWrite": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "config": { "$ref": "#/components/schemas/AppConfig" }, "status": { "type": "string", "enum": [ "active", "disabled" ] } }, "required": [ "name", "config" ], "additionalProperties": false }, "AppResponse": { "type": "object", "properties": { "app": { "type": "object", "properties": { "revision": { "type": "integer", "exclusiveMinimum": 0 }, "id": { "type": "string", "description": "The gateway-assigned id, and the `{app}` segment of every URL for this application." }, "name": { "type": "string" }, "config": { "anyOf": [ { "$ref": "#/components/schemas/AppConfig" }, { "type": "object", "additionalProperties": {} } ] }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "revision", "id", "name", "config", "status", "created_at", "updated_at" ] }, "resolved": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "The configuration as the request path resolves it, with provider routing and limits applied. Null when the stored configuration does not parse, which is the one case `app.config` is not an AppConfig." }, "config_error": { "type": [ "string", "null" ], "description": "Why the stored configuration does not parse, for a row written before a schema change. Always null on create and update, which validate before they write." } }, "required": [ "app", "resolved", "config_error" ] }, "AppUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "config": { "$ref": "#/components/schemas/AppConfig" }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "revision": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "name", "config", "revision" ], "additionalProperties": false }, "Provider": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "openai", "anthropic", "xai", "gemini", "perplexity", "deepseek", "groq", "mistral", "together", "fireworks", "cerebras", "moonshot", "huggingface", "baseten", "bytedance", "openrouter" ] }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,62}$", "description": "The URL segment used under /proxy/{slug}/, unique across your providers." }, "name": { "type": "string" }, "secretHint": { "type": [ "string", "null" ], "description": "Last characters of a direct provider key; null when a shared provider gateway owns the token." }, "providerGatewayId": { "type": [ "string", "null" ] }, "gatewayRoute": { "type": [ "object", "null" ], "properties": { "modelPrefix": { "type": "string", "minLength": 1, "maxLength": 100 }, "providerOnly": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 1, "maxItems": 20 } }, "additionalProperties": false, "description": "How this instance is routed inside its gateway. Always null for a direct instance and for gateways that take no routing configuration, such as Cloudflare AI Gateway." }, "baseUrl": { "type": [ "string", "null" ], "description": "Your own origin replacing the provider type's own base URL, stored canonicalized (https, public host, default port, trailing slash). Null means the provider type's own base URL is used. Always null on a gateway-routed instance, which cannot carry one.", "example": "https://my-resource.openai.azure.com/openai/v1/" }, "pricing": { "$ref": "#/components/schemas/ProviderPricing" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "disabled is a reversible pause: the row keeps its secret, its pricing and its slug, and requests to it fail with provider_disabled until it is enabled again." }, "createdAt": { "type": "string" }, "createdBy": { "type": "string" } }, "required": [ "id", "type", "slug", "name", "secretHint", "providerGatewayId", "gatewayRoute", "baseUrl", "pricing", "status", "createdAt", "createdBy" ] }, "ProviderPricing": { "type": [ "object", "null" ], "additionalProperties": { "type": "object", "properties": { "input": { "type": "number", "minimum": 0 }, "output": { "type": "number", "minimum": 0 } }, "required": [ "input", "output" ], "additionalProperties": false } }, "ProviderCreateRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "openai", "anthropic", "xai", "gemini", "perplexity", "deepseek", "groq", "mistral", "together", "fireworks", "cerebras", "moonshot", "huggingface", "baseten", "bytedance", "openrouter" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,62}$" }, "secret": { "type": "string", "minLength": 1, "maxLength": 4096 }, "providerGatewayId": { "type": "string", "minLength": 1 }, "gatewayRoute": { "$ref": "#/components/schemas/GatewayRouteConfig" }, "baseUrl": { "type": "string", "minLength": 1, "maxLength": 200 }, "pricing": { "$ref": "#/components/schemas/ProviderPricing" } }, "required": [ "type", "name" ], "additionalProperties": false }, "GatewayRouteConfig": { "type": "object", "properties": { "modelPrefix": { "type": "string", "minLength": 1, "maxLength": 100 }, "providerOnly": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 1, "maxItems": 20 } }, "additionalProperties": false }, "ProviderTestRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "openai", "anthropic", "xai", "gemini", "perplexity", "deepseek", "groq", "mistral", "together", "fireworks", "cerebras", "moonshot", "huggingface", "baseten", "bytedance", "openrouter" ] }, "secret": { "type": "string", "minLength": 1, "maxLength": 4096 }, "providerGatewayId": { "type": "string", "minLength": 1 }, "baseUrl": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "type" ], "additionalProperties": false }, "ProviderUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "secret": { "type": "string", "minLength": 1, "maxLength": 4096 }, "gatewayRoute": { "allOf": [ { "$ref": "#/components/schemas/GatewayRouteConfig" }, { "type": [ "object", "null" ] } ] }, "baseUrl": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 }, "pricing": { "$ref": "#/components/schemas/ProviderPricing" }, "status": { "type": "string", "enum": [ "active", "disabled" ] } }, "additionalProperties": false }, "ProviderGateway": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "secretHint": { "type": "string", "description": "The last characters of the gateway token. The token itself is never returned." }, "providerCount": { "type": "integer", "minimum": 0, "description": "Active provider instances routed through this gateway." }, "referencedCount": { "type": "integer", "minimum": 0, "description": "All provider instances referencing this gateway, including disabled rows retained for re-enabling. Deletion is refused while this is above zero." }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "createdBy": { "type": "string" }, "type": { "type": "string", "enum": [ "cf_aig" ] }, "config": { "type": "object", "properties": { "accountId": { "type": "string" }, "gatewayId": { "type": "string" } }, "required": [ "accountId", "gatewayId" ] } }, "required": [ "id", "name", "secretHint", "providerCount", "referencedCount", "status", "createdAt", "updatedAt", "createdBy", "type", "config" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "secretHint": { "type": "string", "description": "The last characters of the gateway token. The token itself is never returned." }, "providerCount": { "type": "integer", "minimum": 0, "description": "Active provider instances routed through this gateway." }, "referencedCount": { "type": "integer", "minimum": 0, "description": "All provider instances referencing this gateway, including disabled rows retained for re-enabling. Deletion is refused while this is above zero." }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "createdBy": { "type": "string" }, "type": { "type": "string", "enum": [ "vercel" ] }, "config": { "type": "object", "properties": {}, "description": "Vercel's origin is fixed in adapter code, so it has no configuration of its own." } }, "required": [ "id", "name", "secretHint", "providerCount", "referencedCount", "status", "createdAt", "updatedAt", "createdBy", "type", "config" ] } ] }, "ProviderGatewayCreateRequest": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cf_aig" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "accountId": { "type": "string", "minLength": 1, "maxLength": 100 }, "gatewayId": { "type": "string", "minLength": 1, "maxLength": 100 }, "token": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "type", "name", "accountId", "gatewayId", "token" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "vercel" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "token": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "type", "name", "token" ], "additionalProperties": false } ] }, "ProviderGatewayTestRequest": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cf_aig" ] }, "accountId": { "type": "string", "minLength": 1, "maxLength": 100 }, "gatewayId": { "type": "string", "minLength": 1, "maxLength": 100 }, "token": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "type", "accountId", "gatewayId", "token" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "vercel" ] }, "token": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "type", "token" ], "additionalProperties": false } ] }, "ProviderGatewayUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name" ], "additionalProperties": false }, "ProviderGatewayRotateRequest": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "token" ], "additionalProperties": false }, "OrganizationSelectRequest": { "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ] }, "UsageEvent": { "type": "object", "properties": { "id": { "type": "integer" }, "user_id": { "type": [ "string", "null" ] }, "api_key_id": { "type": [ "string", "null" ], "description": "Non-secret ID of the application API key that authenticated the request, including the client-proof key carried by an exchanged gateway token." }, "provider": { "type": "string" }, "provider_slug": { "type": [ "string", "null" ] }, "provider_gateway_id": { "type": [ "string", "null" ], "description": "The gateway connection that carried the request, or null for a direct call. Recorded for every routed request; the id is kept even after the gateway row is deleted." }, "provider_gateway_type": { "type": [ "string", "null" ], "description": "That gateway's type at request time, for example cf_aig." }, "credential_source": { "type": [ "string", "null" ], "enum": [ "direct", "byok", "gateway_system", "unknown", null ], "description": "Whose credential paid, where something settles it: `direct` for an instance holding its own key, `byok` when a gateway serves it from your own key store or when a reporting upstream says your own key paid for the inference. Never inferred from a successful response; null when nothing settles it." }, "model_author": { "type": [ "string", "null" ], "description": "Who made the model, resolved when the event was recorded. An analytics dimension only — it never affects budgets or allowlists." }, "served_provider": { "type": [ "string", "null" ], "description": "The serving provider the upstream named, when it names one — the host OpenRouter routed to, for instance. Null means unknown, never a guarantee." }, "served_model": { "type": [ "string", "null" ], "description": "The serving model the upstream named, canonicalized back to the provider's own model ID." }, "model": { "type": "string" }, "route": { "type": "string" }, "endpoint_slug": { "type": [ "string", "null" ] }, "input_tokens": { "type": "integer" }, "cached_input_tokens": { "type": "integer" }, "cache_write_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "cost_usd": { "type": "number" }, "reported_cost_usd": { "type": [ "number", "null" ], "description": "What the upstream said the request cost, on routes that report one. Null everywhere else; cost_usd stays the billed figure either way." }, "cost_source": { "type": [ "string", "null" ], "enum": [ "computed", "reported", "unresolved", null ], "description": "How cost_usd was determined. `reported` is the upstream's own figure for this request, which is what was billed; `computed` is this deployment's price catalog; `unresolved` means the provider answered successfully but neither source could establish a cost, so the zero is unknown rather than measured. Null on blocked traffic and on events recorded before this field existed." }, "app_version": { "type": [ "string", "null" ] }, "auth_method": { "type": [ "string", "null" ], "enum": [ "attest", "api_key", null ] }, "status": { "type": "string", "enum": [ "ok", "provider_error", "blocked_app_rate", "blocked_app_budget", "blocked_billing", "blocked_user" ] }, "client_aborted": { "type": [ "integer", "null" ], "description": "1 when the client disconnected before the upstream finished streaming, which cancelled the provider call; null otherwise. Not a failure — the request was served as far as the caller wanted it — but an aborted stream often takes the provider's end-of-response usage with it, which is why such an event may carry cost_source unresolved." }, "latency_ms": { "type": [ "integer", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "user_id", "api_key_id", "provider", "provider_slug", "provider_gateway_id", "provider_gateway_type", "credential_source", "model_author", "served_provider", "served_model", "model", "route", "endpoint_slug", "input_tokens", "cached_input_tokens", "cache_write_tokens", "output_tokens", "cost_usd", "reported_cost_usd", "cost_source", "app_version", "auth_method", "status", "client_aborted", "latency_ms", "created_at" ] }, "AuthEventSummary": { "type": "object", "properties": { "app_id": { "type": "string" }, "days": { "type": "integer" }, "from": { "type": "string" }, "to": { "type": "string" }, "daily": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "event": { "type": "string", "enum": [ "token_exchange", "register" ] }, "outcome": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "count": { "type": "integer" } }, "required": [ "date", "event", "outcome", "reason", "count" ] }, "description": "Authentication attempts per day, grouped by outcome and granular reason." }, "usage_failures": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "status": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "date", "status", "count" ] }, "description": "Non-ok proxied requests per day, so proxy-path failures appear in the same view." }, "token_exchange": { "type": "object", "properties": { "total": { "type": "integer" }, "ok": { "type": "integer" }, "success_rate": { "type": [ "number", "null" ], "description": "Null when the window contains no exchanges at all, which is not the same as a perfect score." } }, "required": [ "total", "ok", "success_rate" ] }, "claim_delay": { "type": "object", "properties": { "count": { "type": "integer" }, "avg_ms": { "type": [ "number", "null" ] }, "p50_ms": { "type": [ "number", "null" ] }, "p95_ms": { "type": [ "number", "null" ] } }, "required": [ "count", "avg_ms", "p50_ms", "p95_ms" ], "description": "How long users waited for a required entitlement claim to propagate, over the window." }, "pending_users": { "type": "integer", "description": "Users currently inside an unclosed claim-propagation window — stuck mid-activation right now." } }, "required": [ "app_id", "days", "from", "to", "daily", "usage_failures", "token_exchange", "claim_delay", "pending_users" ] }, "AuthEvent": { "type": "object", "properties": { "id": { "type": "integer" }, "user_id": { "type": [ "string", "null" ], "description": "The verified issuer identity, where the attempt got far enough to establish one. Null for attempts refused before any identity was trusted." }, "event": { "type": "string", "enum": [ "token_exchange", "register" ] }, "auth_method": { "type": [ "string", "null" ], "enum": [ "attest", "api_key", null ] }, "outcome": { "type": "string", "description": "`ok`, or the error code the client was handed — for example issuer_claims_missing, issuer_token_rejected, attest_failed." }, "reason": { "type": [ "string", "null" ], "description": "The granular cause behind the outcome, for example claims_missing, bad_signature, jwks_unreachable. Diagnostic only: clients never see it." }, "app_version": { "type": [ "string", "null" ] }, "latency_ms": { "type": [ "integer", "null" ] }, "claim_delay_ms": { "type": [ "integer", "null" ], "description": "Set only on the exchange that ended a claim-propagation window: how long the user waited from their first issuer_claims_missing rejection." }, "created_at": { "type": "string" } }, "required": [ "id", "user_id", "event", "auth_method", "outcome", "reason", "app_version", "latency_ms", "claim_delay_ms", "created_at" ] }, "UsageRepriceRequest": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "anthropic", "xai", "gemini", "perplexity", "deepseek", "groq", "mistral", "together", "fireworks", "cerebras", "moonshot", "huggingface", "baseten", "bytedance", "openrouter" ] }, "model": { "type": "string", "minLength": 1 }, "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "apply": { "type": "boolean", "default": false } }, "required": [ "provider", "model", "month" ], "additionalProperties": false } }, "parameters": {} }, "paths": { "/v1/healthz": { "get": { "tags": [ "Operations" ], "operationId": "getHealth", "summary": "Check gateway health", "responses": { "200": { "description": "The Worker is accepting requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "service": { "type": "string", "enum": [ "app-ai-gateway" ] }, "vault": { "type": "string", "enum": [ "ok", "misconfigured" ] } }, "required": [ "ok", "service", "vault" ] } } } } } } }, "/v1/console/capabilities": { "get": { "tags": [ "Operations" ], "operationId": "getConsoleCapabilities", "summary": "Discover optional deployment capabilities", "responses": { "200": { "description": "Capabilities the console adapts to.", "content": { "application/json": { "schema": { "type": "object", "properties": { "billing": { "type": "boolean" }, "registrationOpen": { "type": "boolean" }, "googleAuth": { "type": "boolean" }, "termsOfServiceUrl": { "type": "string", "format": "uri" }, "privacyPolicyUrl": { "type": "string", "format": "uri" }, "apiBaseUrl": { "type": "string", "format": "uri" } }, "required": [ "billing", "registrationOpen", "googleAuth" ] } } } } } } }, "/v1/auth/sign-up/email": { "post": { "tags": [ "Console authentication" ], "operationId": "signUp", "summary": "Create an account", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8 } }, "required": [ "name", "email", "password" ] } } } }, "responses": { "200": { "description": "Authenticated session.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/auth/sign-in/email": { "post": { "tags": [ "Console authentication" ], "operationId": "signIn", "summary": "Sign in with email and password", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "Authenticated session.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/auth/get-session": { "get": { "tags": [ "Console authentication" ], "operationId": "getSession", "summary": "Get the current session", "security": [ { "ConsoleSession": [] } ], "responses": { "200": { "description": "Current session or null.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/auth/sign-out": { "post": { "tags": [ "Console authentication" ], "operationId": "signOut", "summary": "End the current session", "security": [ { "ConsoleSession": [] } ], "responses": { "200": { "description": "Session ended.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/auth/sign-in/social": { "get": { "tags": [ "Console authentication" ], "operationId": "signInWithGoogle", "summary": "Start optional Google sign-in", "description": "Available only when GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are configured.", "parameters": [ { "schema": { "type": "string", "enum": [ "google" ] }, "required": true, "name": "provider", "in": "query" } ], "responses": { "302": { "description": "Redirect to Google." }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/apps/{app}/auth/challenge": { "post": { "tags": [ "Application authentication" ], "operationId": "createAppAttestChallenge", "summary": "Create an App Attest challenge", "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" } ], "responses": { "200": { "description": "A five-minute, single-use challenge.", "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge": { "type": "string" }, "expires_in": { "type": "number" } }, "required": [ "challenge", "expires_in" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "No billing plan resolves for the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "This application identifies no end users, so there is no per-user standing to report. Answered with auth_method_not_supported: the request was well-formed, and nothing the caller can rephrase would make it work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/apps/{app}/auth/register": { "post": { "tags": [ "Application authentication" ], "operationId": "registerAppAttestKey", "summary": "Register an App Attest key", "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppAttestRegisterRequest" } } } }, "responses": { "200": { "description": "The key was registered for the verified issuer identity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" } }, "required": [ "user_id" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "No billing plan resolves for the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "`issuer_token_rejected` — the token did not verify; get a fresh one, retry once, then fail. `issuer_claims_missing` — the token is valid but a required entitlement claim has not propagated yet; do not re-authenticate, wait and retry. `auth_required` — the key was refused or the user is blocked. `attest_failed` — the App Attest proof did not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "`issuer_verification_unavailable` — the gateway could not reach or read the issuer's keys, so the token was never judged. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/apps/{app}/auth/token": { "post": { "tags": [ "Application authentication" ], "operationId": "exchangeGatewayToken", "summary": "Exchange issuer identity and client proof for a gateway token", "description": "App Attest clients send key_id, assertion, and challenge. Issuer-backed API-key clients send api_key and issuer_token. The verified issuer claim is always the resulting user identity.", "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AppAttestTokenRequest" }, { "$ref": "#/components/schemas/ApiKeyTokenRequest" } ] } } } }, "responses": { "200": { "description": "A short-lived gateway access token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "number" } }, "required": [ "access_token", "expires_in" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "No billing plan resolves for the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "`issuer_token_rejected` — the token did not verify; get a fresh one, retry once, then fail. `issuer_claims_missing` — the token is valid but a required entitlement claim has not propagated yet; do not re-authenticate, wait and retry. `auth_required` — the key was refused or the user is blocked. `attest_failed` — the App Attest proof did not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "`issuer_verification_unavailable` — the gateway could not reach or read the issuer's keys, so the token was never judged. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/apps/{app}/me": { "get": { "tags": [ "Application" ], "operationId": "getCurrentUser", "summary": "Get the current user's limits, spend and block state", "security": [ { "GatewayBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" } ], "responses": { "200": { "description": "Current user state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "limits": { "type": "object", "properties": { "requests_today": { "type": [ "integer", "null" ], "description": "Requests this user has made so far in the current UTC day. Null when the application sets no per-user limit, in which case requests are not counted at all." }, "requests_remaining": { "type": [ "integer", "null" ], "description": "What is left of requests_per_day. Null when no daily limit is set." }, "requests_per_minute": { "type": [ "number", "null" ], "description": "The per-user per-minute limit this app sets. Null means unlimited." }, "requests_per_day": { "type": [ "number", "null" ], "description": "The per-user per-day limit this app sets. Null means unlimited." }, "monthly_cost_usd": { "type": "number", "description": "What this user's traffic has cost so far in the current UTC calendar month." }, "monthly_budget_usd": { "type": [ "number", "null" ], "description": "The per-user monthly spending budget this app sets. Null means unlimited." }, "blocked": { "type": "boolean", "description": "Whether this user has been blocked in the console." } }, "required": [ "requests_today", "requests_remaining", "requests_per_minute", "requests_per_day", "monthly_cost_usd", "monthly_budget_usd", "blocked" ], "description": "The limits the app sets on this user, and where the user stands against them. The account's request allowance is not reported here: it is shared by all apps, and is reported on the rejection that spends it." } }, "required": [ "user_id", "limits" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "No billing plan resolves for the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "This application identifies no end users, so there is no per-user standing to report. Answered with auth_method_not_supported: the request was well-formed, and nothing the caller can rephrase would make it work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/apps/{app}/proxy/{provider}/{path}": { "post": { "tags": [ "Provider proxy" ], "operationId": "proxyProviderRequest", "summary": "Proxy a provider-native model request", "description": "The path, body, and successful response retain the selected provider's native contract. For example, OpenAI clients send v1/responses or v1/chat/completions; gateway-specific provider slug quirks are never part of the client path. The gateway validates the configured path and model, spends one request from the account's monthly allowance, and streams the upstream response without buffering.", "security": [ { "GatewayBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" }, { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,62}$", "example": "openai-dev" }, "required": true, "name": "provider", "in": "path" }, { "schema": { "type": "string", "description": "The provider's native API path verbatim, without a leading slash.", "example": "v1/responses" }, "required": true, "description": "The provider's native API path verbatim, without a leading slash.", "name": "path", "in": "path" }, { "schema": { "type": "string", "description": "Required for gateway-token clients; optional for issuer-less API-key clients." }, "required": false, "description": "Required for gateway-token clients; optional for issuer-less API-key clients.", "name": "x-app-version", "in": "header" }, { "schema": { "type": "string", "description": "Optional configured end-user identity for issuer-less API-key applications." }, "required": false, "description": "Optional configured end-user identity for issuer-less API-key applications.", "name": "x-end-user-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {}, "description": "Provider-native JSON request. Consult the selected provider's API reference for the exact shape." } } } }, "responses": { "200": { "description": "Provider-native response. Streaming responses remain streamed.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "No billing plan resolves for the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Either the app's own limits or the account's request allowance refused the request. The app's limits are checked first and answer app_rate_limited or app_budget_exhausted, carrying scope; the plan allowance answers billing_request_quota_exceeded with limit, used, and the UTC resetAt. Every one of them carries a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream provider request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream provider sent no response headers within the gateway's time-to-first-byte budget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/apps/{app}/endpoints/{slug}": { "post": { "tags": [ "Named endpoints" ], "operationId": "callNamedEndpoint", "summary": "Call a server-configured named endpoint", "description": "The endpoint's provider, model, fixed parameters, output cap, and fallback chain come from the application configuration, so you can change models without shipping a client release. Responses-style endpoints accept an OpenAI Responses body; transcription-style endpoints accept an OpenAI audio transcription multipart body and may omit the model field. The successful response keeps the serving provider's native format and streaming behaviour.", "security": [ { "GatewayBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" }, { "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,64}$", "example": "chat" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string", "description": "Required for gateway-token clients; optional for issuer-less API-key clients." }, "required": false, "description": "Required for gateway-token clients; optional for issuer-less API-key clients.", "name": "x-app-version", "in": "header" }, { "schema": { "type": "string", "description": "Optional configured end-user identity for issuer-less API-key applications." }, "required": false, "description": "Optional configured end-user identity for issuer-less API-key applications.", "name": "x-end-user-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {}, "description": "OpenAI Responses API body for endpoints whose api_style is responses. The gateway overwrites model and deep-merges the configured params." } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "model": { "type": "string", "description": "Ignored; the gateway sets the configured model." }, "prompt": { "type": "string" }, "language": { "type": "string" }, "response_format": { "type": "string" } }, "required": [ "file" ], "description": "Body for endpoints whose api_style is transcription." } } } }, "responses": { "200": { "description": "Provider-native response. Streaming responses remain streamed.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "No billing plan resolves for the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Either the app's own limits or the account's request allowance refused the request. The app's limits are checked first and answer app_rate_limited or app_budget_exhausted, carrying scope; the plan allowance answers billing_request_quota_exceeded with limit, used, and the UTC resetAt. Every one of them carries a Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Every configured target failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Every configured target failed, and the last one sent no response headers within the gateway's time-to-first-byte budget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/apps": { "get": { "tags": [ "Admin applications" ], "operationId": "listApps", "summary": "List applications", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "responses": { "200": { "description": "Applications and current usage summaries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "month": { "type": "string" }, "has_proxied_requests": { "type": "boolean", "description": "Whether this account has ever had a request recorded, at any time. Unlike the per-application `usage` totals beside it, which cover `month` only, this does not reset when a new month begins, and it never goes from true back to false. Intended for first-run interfaces that stop offering setup guidance once traffic has started." }, "apps": { "type": "array", "items": {} } }, "required": [ "month", "has_proxied_requests", "apps" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Admin applications" ], "operationId": "createApp", "summary": "Create an application", "description": "Send only `name`, `config` and an optional `status`. The gateway assigns the id — the name slugified plus a six-character random suffix — and returns it as `app.id`; it cannot be chosen, and it cannot change once the application exists. A body that still carries `id` is refused with `400`. API-key applications receive a one-time plaintext initial key in the response. Optional Idempotency-Key and X-Idempotency-Proof must be supplied together as independently generated 32–256 character URL-safe proofs. Save them before sending; an identical retry returns the original result. Wrong proof is 403, changed body is 409. Protected key recovery lasts 15 minutes; expired recovery never creates another resource.", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" }, "required": false, "name": "Idempotency-Key", "in": "header" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" }, "required": false, "name": "X-Idempotency-Proof", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppWrite" } } } }, "responses": { "201": { "description": "Application created. `app.id` is the assigned id and the segment every gateway URL for this app uses. `api_key` is the one-time plaintext initial key for an API-key application, and null for any other.", "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "type": "object", "properties": { "revision": { "type": "integer", "exclusiveMinimum": 0 }, "id": { "type": "string", "description": "The gateway-assigned id, and the `{app}` segment of every URL for this application." }, "name": { "type": "string" }, "config": { "anyOf": [ { "$ref": "#/components/schemas/AppConfig" }, { "type": "object", "additionalProperties": {} } ] }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "revision", "id", "name", "config", "status", "created_at", "updated_at" ] }, "resolved": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "The configuration as the request path resolves it, with provider routing and limits applied. Null when the stored configuration does not parse, which is the one case `app.config` is not an AppConfig." }, "config_error": { "type": [ "string", "null" ], "description": "Why the stored configuration does not parse, for a row written before a schema change. Always null on create and update, which validate before they write." }, "api_key": {} }, "required": [ "app", "resolved", "config_error" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A request proof was reused with different content or resource creation conflicted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "resource_receipt_expired: protected key recovery expired; error.data contains existing appId/keyId when available. resource_key_unavailable: the original key was revoked. Inspect that resource and replace its key intentionally.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/apps/{app}": { "get": { "tags": [ "Admin applications" ], "operationId": "getApp", "summary": "Get an application", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" } ], "responses": { "200": { "description": "Application state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponse" } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Admin applications" ], "operationId": "updateApp", "summary": "Update an application", "description": "Requires `revision` in the body, the one the application was read at; a stale revision answers `409 app_revision_conflict` and an absent one `400 app_revision_required`. Updates an existing application in place. It never creates one: an id none of your applications holds answers `404 app_not_found`, and nothing is written. Applications are created only by `POST /v1/admin/apps`, which assigns the id.", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppUpdate" } } } }, "responses": { "200": { "description": "Application state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponse" } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The application changed since it was read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Admin applications" ], "operationId": "deleteApp", "summary": "Delete an application and its associated operational data", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "confirm", "in": "query" } ], "responses": { "200": { "description": "Application deleted. Its usage events are kept, which is what `usage_events_retained` reports.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "app_id": { "type": "string" }, "removed_users": { "type": "integer" }, "usage_events_retained": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted", "app_id", "removed_users", "usage_events_retained" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/apps/{app}/validate": { "post": { "tags": [ "Admin applications" ], "operationId": "validateApp", "summary": "Validate an application configuration without saving it", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppWrite" } } } }, "responses": { "200": { "description": "Resolved valid configuration.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/keys": { "get": { "tags": [ "Admin management keys" ], "operationId": "listManagementKeys", "summary": "List management keys", "description": "Console session only. Management keys cannot administer management keys.", "security": [ { "ConsoleSession": [] } ], "responses": { "200": { "description": "Management key metadata without plaintext tokens.", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "userId": { "type": "string" }, "name": { "type": "string" }, "tokenHint": { "type": "string", "description": "Last four characters of the token for display.", "example": "x9Qb" }, "enabled": { "type": "boolean", "description": "Whether the key may authenticate. False for a revoked key, and for one issued by a trusted exchange that has not committed yet." }, "expiresAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "revokedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "organizationId", "userId", "name", "tokenHint", "enabled", "expiresAt", "createdAt", "revokedAt" ] } } }, "required": [ "keys" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Admin management keys" ], "operationId": "createManagementKey", "summary": "Create a management key", "description": "Console session only, and requires the owner or admin role. A management key cannot create another one, so revoking a key you handed out ends that access for good. The plaintext agw_mgmt_ token is returned once, and never expires; the account's own deadline is the only one.", "security": [ { "ConsoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "One-time plaintext management key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "userId": { "type": "string" }, "name": { "type": "string" }, "tokenHint": { "type": "string", "description": "Last four characters of the token for display.", "example": "x9Qb" }, "enabled": { "type": "boolean", "description": "Whether the key may authenticate. False for a revoked key, and for one issued by a trusted exchange that has not committed yet." }, "expiresAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "revokedAt": { "type": [ "string", "null" ] }, "plaintext": { "type": "string" } }, "required": [ "id", "organizationId", "userId", "name", "tokenHint", "enabled", "expiresAt", "createdAt", "revokedAt", "plaintext" ] } }, "required": [ "key" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/keys/{id}/revoke": { "post": { "tags": [ "Admin management keys" ], "operationId": "revokeManagementKey", "summary": "Revoke a management key", "description": "Console session only, and requires the owner or admin role.", "security": [ { "ConsoleSession": [] } ], "parameters": [ { "schema": { "type": "string", "example": "key_123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Revoked management key metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "userId": { "type": "string" }, "name": { "type": "string" }, "tokenHint": { "type": "string", "description": "Last four characters of the token for display.", "example": "x9Qb" }, "enabled": { "type": "boolean", "description": "Whether the key may authenticate. False for a revoked key, and for one issued by a trusted exchange that has not committed yet." }, "expiresAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "revokedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "organizationId", "userId", "name", "tokenHint", "enabled", "expiresAt", "createdAt", "revokedAt" ] } }, "required": [ "key" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/providers": { "get": { "tags": [ "Admin providers" ], "operationId": "listProviders", "summary": "List provider credentials", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "responses": { "200": { "description": "Provider metadata without credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } } }, "required": [ "providers" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Admin providers" ], "operationId": "createProvider", "summary": "Store a provider credential", "description": "Creates one named provider instance. Supply exactly one direct provider secret or reusable providerGatewayId. The credential is stored as given and never probed: check one first with POST /v1/admin/providers/test. The slug defaults to the provider type and is unique among your provider instances, disabled ones included; only deleting an instance frees its slug. Optional Idempotency-Key and X-Idempotency-Proof must be supplied together as independently generated 32–256 character URL-safe proofs. Save them before sending; an identical retry returns the original result. Wrong proof is 403, changed body is 409. Protected key recovery lasts 15 minutes; expired recovery never creates another resource.", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" }, "required": false, "name": "Idempotency-Key", "in": "header" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" }, "required": false, "name": "X-Idempotency-Proof", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderCreateRequest" } } } }, "responses": { "201": { "description": "Stored provider.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/Provider" } }, "required": [ "provider" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A request proof was reused with different content or resource creation conflicted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "resource_receipt_expired: protected key recovery expired; error.data contains existing appId/keyId when available. resource_key_unavailable: the original key was revoked. Inspect that resource and replace its key intentionally.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/providers/test": { "post": { "tags": [ "Admin providers" ], "operationId": "testProviderCredential", "summary": "Probe a provider credential without storing it", "description": "Calls the provider with a credential, and reports what it answered. Nothing is stored, and no other endpoint runs this check: a write stores what it is given. Supply exactly one direct provider secret or an existing providerGatewayId.", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderTestRequest" } } } }, "responses": { "200": { "description": "Probe outcome.", "content": { "application/json": { "schema": { "type": "object", "properties": { "validated": { "type": "boolean", "description": "Whether the live probe confirmed the credential. false means the probe was inconclusive (provider outage, or no probe exists for this provider), not that the credential is bad — a credential the provider refuses fails this request with provider_key_invalid." }, "reason": { "type": "string", "enum": [ "no_probe", "unreachable", "unexpected_status" ], "description": "Why an unvalidated probe proved nothing. Absent when validated is true." }, "status": { "type": "integer", "description": "The upstream status behind an unexpected_status or rejected reason." } }, "required": [ "validated" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/providers/{id}": { "put": { "tags": [ "Admin providers" ], "operationId": "updateProvider", "summary": "Rotate a credential, rename it, move it to another origin, replace its custom pricing, or disable it", "description": "Sending status disables or re-enables the instance. Disabling keeps the secret, the pricing and the slug, so requests to it fail with provider_disabled and no other instance can take its slug meanwhile. Re-enabling therefore always succeeds. Sending a non-null baseUrl also requires secret in the same request: the stored key is write-only and is never decrypted to be sent to an origin it has not been sent to before, so a move carries the key it is to be used with. Sending baseUrl: null returns the instance to its provider type's own origin and needs nothing else.", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "b0a1…" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderUpdateRequest" } } } }, "responses": { "200": { "description": "Updated provider.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/Provider" } }, "required": [ "provider" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Admin providers" ], "operationId": "deleteProvider", "summary": "Delete a provider credential and its custom pricing", "description": "A hard delete, secret and pricing included. Applications using this provider start failing with provider_not_configured within a minute. To pause an instance reversibly instead, send status: \"disabled\" to PUT /v1/admin/providers/{id}.", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "b0a1…" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Provider deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "provider_id": { "type": "string" } }, "required": [ "deleted", "provider_id" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/provider-gateways": { "get": { "tags": [ "Admin provider gateways" ], "operationId": "listProviderGateways", "summary": "List reusable provider gateways", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "responses": { "200": { "description": "Provider gateway metadata without tokens.", "content": { "application/json": { "schema": { "type": "object", "properties": { "gateways": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderGateway" } } }, "required": [ "gateways" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Admin provider gateways" ], "operationId": "createProviderGateway", "summary": "Create a reusable provider gateway connection", "description": "Cloudflare AI Gateway takes an account and gateway id; Vercel AI Gateway takes only a name and a token. The token is encrypted and stored as given, never probed: check a connection first with POST /v1/admin/provider-gateways/test. Provider instances are attached separately through the providers API. Optional Idempotency-Key and X-Idempotency-Proof must be supplied together as independently generated 32–256 character URL-safe proofs. Save them before sending; an identical retry returns the original result. Wrong proof is 403, changed body is 409. Protected key recovery lasts 15 minutes; expired recovery never creates another resource.", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" }, "required": false, "name": "Idempotency-Key", "in": "header" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" }, "required": false, "name": "X-Idempotency-Proof", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderGatewayCreateRequest" } } } }, "responses": { "201": { "description": "Created provider gateway.", "content": { "application/json": { "schema": { "type": "object", "properties": { "gateway": { "$ref": "#/components/schemas/ProviderGateway" } }, "required": [ "gateway" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A request proof was reused with different content or resource creation conflicted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "resource_receipt_expired: protected key recovery expired; error.data contains existing appId/keyId when available. resource_key_unavailable: the original key was revoked. Inspect that resource and replace its key intentionally.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/provider-gateways/test": { "post": { "tags": [ "Admin provider gateways" ], "operationId": "testProviderGateway", "summary": "Probe a gateway connection without storing it", "description": "Calls the gateway with a token, and reports what it answered. Nothing is stored, and no other endpoint runs this check: a write stores what it is given. Unlike the providers API, a refused token is reported as reason: rejected rather than raised as provider_key_invalid, because the same 401 means both a wrong token and a gateway that is not finished being set up.", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderGatewayTestRequest" } } } }, "responses": { "200": { "description": "Probe outcome.", "content": { "application/json": { "schema": { "type": "object", "properties": { "validated": { "type": "boolean", "description": "Whether the live probe confirmed the connection. Unlike the providers API, a refused token is not an error here: a Cloudflare AI Gateway answers 401 both for a wrong token and for a gateway that is not finished being set up, so the verdict is reported as reason: rejected and the caller decides what it means." }, "reason": { "type": "string", "enum": [ "no_probe", "unreachable", "unexpected_status", "rejected" ], "description": "Why the probe did not confirm the connection. Absent when validated is true. rejected means the gateway refused the token." }, "status": { "type": "integer", "description": "The upstream status behind an unexpected_status or rejected reason." } }, "required": [ "validated" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/provider-gateways/{id}": { "patch": { "tags": [ "Admin provider gateways" ], "operationId": "updateProviderGateway", "summary": "Rename a provider gateway", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "b0a1…" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderGatewayUpdateRequest" } } } }, "responses": { "200": { "description": "Updated provider gateway.", "content": { "application/json": { "schema": { "type": "object", "properties": { "gateway": { "$ref": "#/components/schemas/ProviderGateway" } }, "required": [ "gateway" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Admin provider gateways" ], "operationId": "deleteProviderGateway", "summary": "Delete an unused provider gateway", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "b0a1…" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Provider gateway deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "provider_gateway_id": { "type": "string" } }, "required": [ "deleted", "provider_gateway_id" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Provider instances still reference this gateway. Disabled rows are retained for re-enabling and block deletion too; see referencedCount.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/provider-gateways/{id}/rotate": { "post": { "tags": [ "Admin provider gateways" ], "operationId": "rotateProviderGateway", "summary": "Rotate a shared provider gateway token", "description": "Re-encrypts the token once for every provider instance referencing this gateway. The new token is stored as given, never probed.", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "b0a1…" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderGatewayRotateRequest" } } } }, "responses": { "200": { "description": "Rotated provider gateway.", "content": { "application/json": { "schema": { "type": "object", "properties": { "gateway": { "$ref": "#/components/schemas/ProviderGateway" } }, "required": [ "gateway" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/session": { "get": { "tags": [ "Admin organizations" ], "operationId": "getAdminSession", "summary": "Get the caller's identity, current organization and role", "description": "The console needs the caller's role and active organization to gate its UI; the sign-in session endpoint reports neither.", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "responses": { "200": { "description": "Resolved session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "user": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "human", "service" ] }, "emailVerified": { "type": "boolean" }, "image": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "email", "kind", "emailVerified", "image", "createdAt" ] }, "organization": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" }, "claimed": { "type": "boolean" }, "expiresAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "createdAt", "claimed", "expiresAt" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" }, "claimed": { "type": "boolean" }, "expiresAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "createdAt", "claimed", "expiresAt" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "status": { "type": "string", "enum": [ "active" ] }, "joinedAt": { "type": "string" } }, "required": [ "organization", "role", "status", "joinedAt" ] } }, "credentialType": { "type": "string", "enum": [ "session", "apiKey" ] }, "assurance": { "type": [ "string", "null" ], "enum": [ "interactive", "credential", null ] }, "actor": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "human", "service" ] }, "credentialId": { "type": [ "string", "null" ] }, "actionSource": { "type": "string" } }, "required": [ "type", "id", "kind", "credentialId", "actionSource" ] } }, "required": [ "user", "organization", "role", "memberships", "credentialType", "assurance", "actor" ] } }, "required": [ "session" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/organizations": { "get": { "tags": [ "Admin organizations" ], "operationId": "listOrganizations", "summary": "List the organizations the caller belongs to", "security": [ { "ConsoleSession": [] } ], "responses": { "200": { "description": "Memberships ordered by organization creation time.", "content": { "application/json": { "schema": { "type": "object", "properties": { "organizations": { "type": "array", "items": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" }, "claimed": { "type": "boolean" }, "expiresAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "createdAt", "claimed", "expiresAt" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "status": { "type": "string", "enum": [ "active" ] }, "joinedAt": { "type": "string" } }, "required": [ "organization", "role", "status", "joinedAt" ] } } }, "required": [ "organizations" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/organizations/select": { "post": { "tags": [ "Admin organizations" ], "operationId": "selectOrganization", "summary": "Switch the caller's active organization", "description": "Available to every member, including read-only members, of the target organization.", "security": [ { "ConsoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSelectRequest" } } } }, "responses": { "200": { "description": "Session rescoped to the selected organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "user": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "human", "service" ] }, "emailVerified": { "type": "boolean" }, "image": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "email", "kind", "emailVerified", "image", "createdAt" ] }, "organization": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" }, "claimed": { "type": "boolean" }, "expiresAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "createdAt", "claimed", "expiresAt" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" }, "claimed": { "type": "boolean" }, "expiresAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "createdAt", "claimed", "expiresAt" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "status": { "type": "string", "enum": [ "active" ] }, "joinedAt": { "type": "string" } }, "required": [ "organization", "role", "status", "joinedAt" ] } }, "credentialType": { "type": "string", "enum": [ "session", "apiKey" ] }, "assurance": { "type": [ "string", "null" ], "enum": [ "interactive", "credential", null ] }, "actor": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "human", "service" ] }, "credentialId": { "type": [ "string", "null" ] }, "actionSource": { "type": "string" } }, "required": [ "type", "id", "kind", "credentialId", "actionSource" ] } }, "required": [ "user", "organization", "role", "memberships", "credentialType", "assurance", "actor" ] } }, "required": [ "session" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/apps/{app}/events": { "get": { "operationId": "listAppEvents", "summary": "List application usage events", "tags": [ "Admin operations" ], "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" } ], "responses": { "200": { "description": "Paginated application usage events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "app_id": { "type": "string" }, "limit": { "type": "integer" }, "next_before_id": { "type": [ "integer", "null" ] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/UsageEvent" } } }, "required": [ "app_id", "limit", "next_before_id", "events" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/apps/{app}/auth-events/summary": { "get": { "operationId": "getAppAuthEventSummary", "summary": "Summarize application authentication outcomes", "description": "Daily authentication outcomes and reasons, non-ok proxied requests, token-exchange success rate, entitlement-claim propagation delays, and how many users are waiting on a claim right now.", "tags": [ "Admin operations" ], "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Trailing window in days, ending today. Defaults to 30." }, "required": false, "description": "Trailing window in days, ending today. Defaults to 30.", "name": "days", "in": "query" } ], "responses": { "200": { "description": "Authentication activity for the window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthEventSummary" } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/apps/{app}/auth-events": { "get": { "operationId": "listAppAuthEvents", "summary": "List application authentication events", "tags": [ "Admin operations" ], "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" } ], "responses": { "200": { "description": "Paginated authentication attempts, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "app_id": { "type": "string" }, "limit": { "type": "integer" }, "next_before_id": { "type": [ "integer", "null" ] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/AuthEvent" } } }, "required": [ "app_id", "limit", "next_before_id", "events" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/apps/{app}/keys": { "get": { "operationId": "listAppKeys", "summary": "List application API keys", "tags": [ "Admin operations" ], "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "createAppKey", "summary": "Create an application API key", "tags": [ "Admin operations" ], "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "description": " Optional Idempotency-Key and X-Idempotency-Proof must be supplied together as independently generated 32–256 character URL-safe proofs. Save them before sending; an identical retry returns the original result. Wrong proof is 403, changed body is 409. Protected key recovery lasts 15 minutes; expired recovery never creates another resource.", "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" }, "required": false, "name": "Idempotency-Key", "in": "header" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" }, "required": false, "name": "X-Idempotency-Proof", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A request proof was reused with different content or resource creation conflicted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "resource_receipt_expired: protected key recovery expired; error.data contains existing appId/keyId when available. resource_key_unavailable: the original key was revoked. Inspect that resource and replace its key intentionally.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/apps/{app}/keys/{key}/revoke": { "post": { "operationId": "revokeAppKey", "summary": "Revoke an application API key", "tags": [ "Admin operations" ], "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" }, { "schema": { "type": "string", "example": "key_123" }, "required": true, "name": "key", "in": "path" } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/apps/{app}/users": { "get": { "operationId": "listAppUsers", "summary": "List application users", "tags": [ "Admin operations" ], "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/apps/{app}/users/{user}": { "get": { "operationId": "getAppUser", "summary": "Get an application user", "tags": [ "Admin operations" ], "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" }, { "schema": { "type": "string", "example": "user-123" }, "required": true, "name": "user", "in": "path" } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/apps/{app}/users/{user}/block": { "post": { "operationId": "blockAppUser", "summary": "Block an application user", "tags": [ "Admin operations" ], "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" }, { "schema": { "type": "string", "example": "user-123" }, "required": true, "name": "user", "in": "path" } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/apps/{app}/users/{user}/unblock": { "post": { "operationId": "unblockAppUser", "summary": "Unblock an application user", "tags": [ "Admin operations" ], "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" }, { "schema": { "type": "string", "example": "user-123" }, "required": true, "name": "user", "in": "path" } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/apps/{app}/usage": { "get": { "operationId": "getAppUsage", "summary": "Get application usage totals", "tags": [ "Admin operations" ], "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/apps/{app}/usage/reprice": { "post": { "operationId": "repriceAppUsage", "summary": "Preview or apply current catalog prices to stored usage", "tags": [ "Admin operations" ], "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageRepriceRequest" } } } }, "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/apps/{app}/usage/timeseries": { "get": { "operationId": "getAppUsageTimeseries", "summary": "Get application usage over time", "tags": [ "Admin operations" ], "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/apps/{app}/usage/breakdown": { "get": { "operationId": "getAppUsageBreakdown", "summary": "Get grouped application usage", "tags": [ "Admin operations" ], "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "my-app" }, "required": true, "name": "app", "in": "path" } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/prices": { "get": { "operationId": "listModelPrices", "summary": "List known model prices", "tags": [ "Admin models" ], "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/cli/capabilities": { "get": { "tags": [ "CLI" ], "operationId": "getCliCapabilities", "summary": "Discover deployment identity and provider capabilities", "responses": { "200": { "description": "Public deployment capabilities. No credentials or inference calls.", "content": { "application/json": { "schema": { "type": "object", "properties": { "protocolVersion": { "type": "number", "enum": [ 1 ] }, "serverVersion": { "type": "string" }, "deployment": { "type": "object", "properties": { "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "cloud", "self_hosted" ] }, "apiUrl": { "type": "string", "format": "uri" }, "consoleOrigin": { "type": "string", "format": "uri" } }, "required": [ "id", "mode", "apiUrl", "consoleOrigin" ] }, "consoleOrigin": { "type": "string", "format": "uri" }, "providers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "baseUrl": { "type": "string" }, "defaultPath": { "type": "string" }, "apiStyles": { "type": "array", "items": { "type": "string" } }, "endpointStyles": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "name", "baseUrl", "apiStyles", "endpointStyles" ] } }, "providerGateways": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" } }, "required": [ "type", "name" ] } } }, "required": [ "protocolVersion", "serverVersion", "deployment", "consoleOrigin", "providers", "providerGateways" ] } } } } } } }, "/v1/cli/bootstrap": { "post": { "tags": [ "CLI" ], "operationId": "bootstrapCliAccount", "summary": "Initialize a recoverable CLI account", "description": "Persist both random proofs before sending. An identical retry returns the same account and protected credential during its exchange window. Cloud initialization is public and rate limited. Self-hosted initialization is public too and creates the deployment's single initial account, so whoever initializes an empty deployment first owns it, exactly as its first console registration does. All responses are no-store.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" }, "pollToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" } }, "required": [ "idempotencyKey", "pollToken" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Initial account and credential. Never print or log the credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deployment": { "type": "object", "properties": { "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "cloud", "self_hosted" ] }, "apiUrl": { "type": "string", "format": "uri" }, "consoleOrigin": { "type": "string", "format": "uri" } }, "required": [ "id", "mode", "apiUrl", "consoleOrigin" ] }, "account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" }, "claimed": { "type": "boolean" }, "expiresAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "createdAt", "claimed", "expiresAt" ] }, "credential": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] }, "trial": { "type": [ "object", "null" ], "properties": { "endsAt": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "endsAt" ] } }, "required": [ "deployment", "account", "credential", "trial" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A conflicting transition or setup cap prevents this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "The protected credential exchange has expired; no replacement is minted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The durable initiation or submission rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/cli/operations": { "post": { "tags": [ "CLI" ], "operationId": "createCliOperation", "summary": "Create or recover a browser handoff", "description": "Persist pollToken before initiation. Repeating the same proof and payload recovers the same operation. A current account key is required. Claims require interactive human sign-in and explicit consent. Provider handoffs require the browser URL proof and show the exact resource configuration before secret submission. Handoffs expire after 15 minutes.", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "claim", "provider.add", "provider.rotate-key", "provider.update", "provider-gateway.add", "provider-gateway.rotate-key" ] }, "payload": { "type": "object", "additionalProperties": {}, "default": {} }, "pollToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" } }, "required": [ "kind", "pollToken" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Browser URL for the pending handoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "completed", "failed", "expired" ] }, "deployment": { "type": "object", "properties": { "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "cloud", "self_hosted" ] }, "apiUrl": { "type": "string", "format": "uri" }, "consoleOrigin": { "type": "string", "format": "uri" } }, "required": [ "id", "mode", "apiUrl", "consoleOrigin" ] } }, "required": [ "id", "url", "expiresAt", "state", "deployment" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A conflicting transition or setup cap prevents this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "The protected credential exchange has expired; no replacement is minted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The durable initiation or submission rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/cli/operations/{id}": { "get": { "tags": [ "CLI" ], "operationId": "pollCliOperation", "summary": "Poll a browser handoff", "security": [ { "CliPollProof": [] } ], "description": "Only the original polling proof can recover the result. Completed claims report the account they landed on; the CLI keeps the access it already had. Provider secrets are never returned.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Current operation state and nonsecret result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "expiresAt": { "type": "string" }, "deployment": { "type": "object", "properties": { "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "cloud", "self_hosted" ] }, "apiUrl": { "type": "string", "format": "uri" }, "consoleOrigin": { "type": "string", "format": "uri" } }, "required": [ "id", "mode", "apiUrl", "consoleOrigin" ] }, "state": { "type": "string", "enum": [ "pending", "completed", "failed", "expired" ] }, "result": { "type": "object", "properties": { "accountId": { "type": "string" }, "provider": { "$ref": "#/components/schemas/Provider" }, "gateway": { "$ref": "#/components/schemas/ProviderGateway" } } }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" }, "claimed": { "type": "boolean" }, "expiresAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "createdAt", "claimed", "expiresAt" ] } }, "required": [ "id", "expiresAt", "deployment", "state" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A conflicting transition or setup cap prevents this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "The protected credential exchange has expired; no replacement is minted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The durable initiation or submission rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/cli/account": { "get": { "tags": [ "CLI" ], "operationId": "getCliAccount", "summary": "Read account lifecycle and current access", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "responses": { "200": { "description": "Account deadlines, effective access and current request count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deployment": { "type": "object", "properties": { "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "cloud", "self_hosted" ] }, "apiUrl": { "type": "string", "format": "uri" }, "consoleOrigin": { "type": "string", "format": "uri" } }, "required": [ "id", "mode", "apiUrl", "consoleOrigin" ] }, "account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" }, "claimed": { "type": "boolean" }, "expiresAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "createdAt", "claimed", "expiresAt" ] }, "billing": { "type": "object", "additionalProperties": {} }, "usage": { "type": [ "object", "null" ], "additionalProperties": {} } }, "required": [ "deployment", "account", "billing", "usage" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A conflicting transition or setup cap prevents this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "The protected credential exchange has expired; no replacement is minted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The durable initiation or submission rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/cli/usage": { "get": { "tags": [ "CLI" ], "operationId": "getCliUsage", "summary": "Read retained account usage for a UTC month", "security": [ { "ConsoleSession": [] }, { "ManagementBearer": [] } ], "description": "Includes retained usage for deleted apps, with durable account attribution. Historical rows whose owner was already unknown when attribution was introduced cannot be counted. Coverage describes this limitation without disclosing other accounts' data.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "description": "YYYY-MM; defaults to the current UTC month." }, "required": false, "description": "YYYY-MM; defaults to the current UTC month.", "name": "month", "in": "query" } ], "responses": { "200": { "description": "Account totals, per-app totals and attribution coverage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "month": { "type": "string" }, "totals": { "type": "object", "properties": { "requests": { "type": "number" }, "input_tokens": { "type": "number" }, "cached_input_tokens": { "type": "number" }, "cache_write_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "cost_usd": { "type": "number" }, "errors": { "type": "number" }, "blocked": { "type": "number" } }, "required": [ "requests", "input_tokens", "cached_input_tokens", "cache_write_tokens", "output_tokens", "cost_usd", "errors", "blocked" ] }, "apps": { "type": "array", "items": { "type": "object", "properties": { "requests": { "type": "number" }, "input_tokens": { "type": "number" }, "cached_input_tokens": { "type": "number" }, "cache_write_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "cost_usd": { "type": "number" }, "errors": { "type": "number" }, "blocked": { "type": "number" }, "appId": { "type": "string" }, "deleted": { "type": "boolean" }, "firstRecord": { "type": "string" } }, "required": [ "requests", "input_tokens", "cached_input_tokens", "cache_write_tokens", "output_tokens", "cost_usd", "errors", "blocked", "appId", "deleted", "firstRecord" ] } }, "coverage": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "retained_account_usage" ] }, "firstRecord": { "type": [ "string", "null" ] }, "historicalAttribution": { "type": "string" } }, "required": [ "scope", "firstRecord", "historicalAttribution" ] } }, "required": [ "accountId", "month", "totals", "apps", "coverage" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A conflicting transition or setup cap prevents this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "The protected credential exchange has expired; no replacement is minted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The durable initiation or submission rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/cli/browser/{id}/details": { "post": { "tags": [ "CLI" ], "operationId": "cliBrowserDetails", "summary": "Browser handoff: details", "description": "First-party browser only: both the request URL origin and exact Origin header must match consoleOrigin; a separate submissionToken is required. Identity approval also requires an interactive human session; registration is limited to a valid pending claim. Provider secret values are write-only.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "submissionToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" }, "approve": { "type": "boolean", "enum": [ true ] }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8, "maxLength": 256 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "secret": { "type": "string", "maxLength": 16384 } }, "required": [ "submissionToken" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The pending action, its configuration, the account it lands on, the signed-in human who would approve it, if any, and what stands between this browser and approving it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "claim", "provider.add", "provider.rotate-key", "provider.update", "provider-gateway.add", "provider-gateway.rotate-key" ] }, "payload": { "type": "object", "additionalProperties": {} }, "account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" }, "claimed": { "type": "boolean" }, "expiresAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "createdAt", "claimed", "expiresAt" ] }, "viewer": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "email" ] }, "blockedBy": { "type": [ "string", "null" ], "enum": [ "registration_required", "sign_out_required", null ] }, "googleEnabled": { "type": "boolean" }, "expiresAt": { "type": "string" } }, "required": [ "kind", "payload", "account", "viewer", "blockedBy", "googleEnabled", "expiresAt" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A conflicting transition or setup cap prevents this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "The protected credential exchange has expired; no replacement is minted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The durable initiation or submission rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/cli/browser/{id}/submit": { "post": { "tags": [ "CLI" ], "operationId": "cliBrowserSubmit", "summary": "Browser handoff: submit", "description": "First-party browser only: both the request URL origin and exact Origin header must match consoleOrigin; a separate submissionToken is required. Identity approval also requires an interactive human session; registration is limited to a valid pending claim. Provider secret values are write-only.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "submissionToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" }, "approve": { "type": "boolean", "enum": [ true ] }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8, "maxLength": 256 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "secret": { "type": "string", "maxLength": 16384 } }, "required": [ "submissionToken" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The handoff is approved and consumed. No submitted secret is ever echoed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "completed" ] }, "message": { "type": "string" }, "continueTo": { "type": "string", "enum": [ "cli", "console" ] } }, "required": [ "state", "message", "continueTo" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A conflicting transition or setup cap prevents this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "The protected credential exchange has expired; no replacement is minted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The durable initiation or submission rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/cli/browser/{id}/register": { "post": { "tags": [ "CLI" ], "operationId": "cliBrowserRegister", "summary": "Browser handoff: register", "description": "First-party browser only: both the request URL origin and exact Origin header must match consoleOrigin; a separate submissionToken is required. Identity approval also requires an interactive human session; registration is limited to a valid pending claim. Provider secret values are write-only.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "submissionToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" }, "approve": { "type": "boolean", "enum": [ true ] }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8, "maxLength": 256 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "secret": { "type": "string", "maxLength": 16384 } }, "required": [ "submissionToken" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "A new human identity for a pending claim, with its session set as a cookie.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": [ "string", "null" ] }, "redirect": { "type": "boolean" } } } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A conflicting transition or setup cap prevents this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "The protected credential exchange has expired; no replacement is minted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The durable initiation or submission rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/cli/browser/{id}/google": { "post": { "tags": [ "CLI" ], "operationId": "cliBrowserGoogle", "summary": "Browser handoff: google", "description": "First-party browser only: both the request URL origin and exact Origin header must match consoleOrigin; a separate submissionToken is required. Identity approval also requires an interactive human session; registration is limited to a valid pending claim. Provider secret values are write-only.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "submissionToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" }, "approve": { "type": "boolean", "enum": [ true ] }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8, "maxLength": 256 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "secret": { "type": "string", "maxLength": 16384 } }, "required": [ "submissionToken" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Where to send the browser to start Google consent for a pending claim.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "redirect": { "type": "boolean" } }, "required": [ "url" ] } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The authenticated identity is not allowed to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A conflicting transition or setup cap prevents this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "The protected credential exchange has expired; no replacement is minted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The durable initiation or submission rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "webhooks": {} }