{"openapi":"3.1.0","info":{"title":"Odile Gate API","version":"2026-11-18","summary":"An API gateway for AI-built apps: per-app keys, allowed calls, rate limits, loop breaking, approvals and an audit log.","description":"Create a project, register each app with the calls it may make, then send the app's calls to /g/{project_id}/... with its app key. Gate checks the key, the call and the limits, adds your upstream secret, forwards the call and logs it. Since 17 Nov 2026 a new app's writes need a run token (x-odile-run) unless the app was created with runs: \"off\"; apps made earlier keep their mode. Admin routes take the project admin key (or a member key, gm_...) as a Bearer token; approver routes take an approver key (gp_...). Plain-text guide: https://gate.odilelabs.com/llms.txt\n\nAuthentication: Gate uses bearer keys, not OAuth 2.0. Gate authenticates with owner-issued bearer keys. Public discovery and project creation require no account or connection key. Existing-project tools require a project key. App route rules and run grants restrict workloads; team roles restrict management access. There is no delegated authorization or consent service. Keep owner keys out of workloads.\n\nVersioning and deprecation: Send optional Gate-Version: 1; omission selects version 1. Any other value returns 400 with supported_versions before the route runs. Responses carry Gate-Version: 1. This selector applies across the host, including /api and /g; it is not forwarded to an upstream API. OpenAPI info.version is the documentation revision. Compatible additions keep the current paths. Breaking replacements use a separately documented versioned path. Retirement requires at least 90 days notice, a migration path, OpenAPI deprecated: true, and Deprecation and Sunset response headers on affected routes. No route is currently scheduled for retirement, so those retirement headers are not sent.","contact":{"name":"Odile Labs","url":"https://odilelabs.com/gate","email":"hello@odilelabs.com"},"license":{"name":"Proprietary"},"x-api-versioning":{"strategy":"header","requestHeader":"Gate-Version","responseHeader":"Gate-Version","supportedVersions":["1"],"defaultVersion":"1","unsupportedVersionStatus":400,"scope":"All routes on the canonical host; not forwarded upstream.","breakingChanges":"A separately documented versioned replacement path; no silent repurposing.","deprecation":{"scheduled":false,"minimumNoticeDays":90,"signals":["OpenAPI deprecated: true","Deprecation","Sunset"],"policyUrl":"https://gate.odilelabs.com/docs#versions"},"requestVersionSelection":true,"documentationRevision":"2026-11-18"}},"servers":[{"url":"https://gate.odilelabs.com"}],"externalDocs":{"description":"Odile Gate API docs, authentication and agent instructions","url":"https://gate.odilelabs.com/docs"},"tags":[{"name":"Public and account","description":"Odile Gate's public edge in src/index.js: health, account/project creation, the hosted MCP server, declarative config (odile.yaml), x402 bearer-call packs, audit share links, team-invite acceptance, usage-alert unsubscribe, and machine-readable discovery (ai-catalog, llms.txt, demo login, OpenShell manifest). Every one of these runs in the main Worker; project-scoped admin/approval/gateway calls are routed into a per-project Durable Object by toProject() and are out of this fragment's scope."},{"name":"Project admin","description":"Managing a Gate project itself: its summary, team members, admin key, upstream secret, billing, usage packs, alerts, enterprise controls, setup check, metrics, change log and pilot report. Every route here is the public `/api/projects/{project_id}/...` form, proxied by the worker to the project's Durable Object as `/admin/...`."},{"name":"Apps","description":"Register and manage the apps (keys) that call through a Gate project: routes allowed, rate limits, the loop breaker, anomaly guard, response filtering, model allow-lists, signed-request keys, learning mode, suspend/resume, client-handoff shares, and Gate Actions run mode."},{"name":"Actions, approvals and audit","description":"Gate Actions: scoped, time-limited run grants an app uses to call the upstream API through the gateway, their delegation tree and timeline; the held-action approval queue a human approver (or an approver-role team member) decides; and the signed, hash-chained audit log, its tamper-evidence export/verify pair, and its CSV download. The approver-only surface is mounted a second time under /approvals/ with the same handlers for GET project/actions and the decide action."},{"name":"Gateway","description":"The gateway proxy (/g/{project_id}/{path}): forwards an app's allowed calls to the project's own upstream API, enforcing keys, routes, runs, approvals, idempotent retries, the loop breaker, rate and quota limits, and optional response filtering."},{"name":"Agent run endpoints","description":"Calls an agent makes to Gate itself during a Gate Actions run. Never forwarded upstream; logged in the audit as GATE routes. Send the app key as Bearer and the run token in x-odile-run."}],"paths":{"/health":{"get":{"tags":["Public and account"],"operationId":"pubHealth","summary":"Liveness check","description":"Always returns 200 with a fixed JSON body. No auth, no Durable Object call, no side effects. Exists alongside /healthz because some uptime monitors try /health first (review note, 9 Nov 2026).","responses":{"200":{"description":"Worker is running.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean","enum":[true]}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[],"parameters":[{"$ref":"#/components/parameters/GateVersion"}]}},"/healthz":{"get":{"tags":["Public and account"],"operationId":"pubHealthz","summary":"Liveness check (plain text)","description":"Always returns 200 'ok' as plain text. No auth, no Durable Object call, no side effects. This is the path the deploy lane's health check hits (against the workers.dev hostname, not a custom domain).","responses":{"200":{"description":"Worker is running.","content":{"text/plain":{"schema":{"type":"string","enum":["ok"]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[],"parameters":[{"$ref":"#/components/parameters/GateVersion"}]}},"/proof.json":{"get":{"tags":["Public and account"],"operationId":"pubProofStats","summary":"Odile Labs' own Gate usage counts","description":"Public proof-of-use numbers for one configured project (Odile Labs' own busiest project), used on the home page strip and in /llms.txt. The response is read from that project's Durable Object (GET /_internal/proof, DO-internal and out of scope) and cached at Cloudflare's edge for up to 10 minutes per colo regardless of query string. A failed internal read never throws; it falls through to 404 instead of breaking the page. Enabled only when BOTH env vars below are set; this deployment currently has both set, so the route is live.","x-gate-flag":"PROOF_STATS","responses":{"200":{"description":"Cached aggregate counts for the configured project.","headers":{"Cache-Control":{"schema":{"type":"string","enum":["public, max-age=600"]}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubProofStats"}}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"PROOF_STATS is not \"1\", PROOF_PROJECT_ID is not set, or the internal read failed/returned no data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[],"parameters":[{"$ref":"#/components/parameters/GateVersion"}]}},"/api/projects":{"post":{"tags":["Public and account"],"operationId":"pubCreateProject","summary":"Create a Gate project","description":"Creates a new Free-plan project in front of an existing upstream HTTPS API and returns its one-time admin key. Body may be JSON or a form post (application/x-www-form-urlencoded or multipart/form-data, used by the landing-page form); on a form post, errors and the success page are returned as HTML instead of JSON, same status codes. Validation (read from the handler and guard.js): name is required, 1-80 characters, no control characters (C0 or DEL). upstream is required, up to 2048 characters, must parse as a URL, must be https:, must not carry a userinfo, query string or fragment, port must be absent/443/8443, host must be a public DNS name (no IP literal in any form, no 'localhost', no reserved/private TLD-like suffix such as .local/.internal/.test, and no wildcard-DNS-to-IP echo service such as nip.io). header_name is optional; if given it must be a valid HTTP token up to 64 characters and may not be a reserved header (host, content-length, cookie, ...), Authorization is used when omitted, and anything starting with cf-, x-forwarded- or x-gate- is refused. header_value is required when header_name/header_value is supplied, up to 4096 characters, one line (no control characters except nothing after trimming). Before any of this, Gate applies a per-IP rate limit (Cloudflare Rate Limiting binding CREATE_LIMIT, keyed by cf-connecting-ip) and fails closed with 503 if that binding itself is missing from the deploy. If a secret header value was supplied, it is sealed (AES-GCM) before being sent to the new project's Durable Object, which requires key-encryption-key material to be ready (kekReady); if it is not, creation is refused with 503 rather than storing the secret unsealed. On success the new project's Durable Object is initialized (its own /init route, out of scope) with a SHA-256 hash of a freshly generated admin key (ga_<project id>_<32 random bytes, base64url>); the admin key itself is returned exactly once and never stored in plaintext. A funnel event is recorded (internal) and a pilot/webhook event gate.project_created is fired with where the call came from (form, api, or mcp via the x-gate-via header the MCP tool layer sets).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubCreateProjectRequest"},"example":{"name":"Demo Desk","upstream":"https://sandbox.gate.odilelabs.com"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PubCreateProjectRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PubCreateProjectRequest"}}}},"responses":{"201":{"description":"Project created. JSON for an API/MCP caller; an HTML 'created' page for a form post.","headers":{"Cache-Control":{"schema":{"type":"string","enum":["no-store"]}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/CreationLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/CreationPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubCreateProjectResponse"}},"text/html":{"schema":{"type":"string"}}}},"400":{"description":"Body is not an object (and not valid form/JSON), or name/upstream/header_name/header_value failed validation (see description). Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}},"text/html":{"schema":{"type":"string"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/CreationLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/CreationPolicy"}}},"429":{"description":"Too many new projects from this IP address in the current rate-limit window.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"text/html":{"schema":{"type":"string"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/CreationLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/CreationPolicy"},"Retry-After":{"description":"Retry advice: 60 seconds. The creation limiter returns no remaining count or reset timestamp; admission is not guaranteed.","schema":{"type":"string"}}}},"500":{"description":"The new project's Durable Object did not initialize; try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"text/html":{"schema":{"type":"string"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/CreationLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/CreationPolicy"}}},"503":{"description":"Project creation is not configured (CREATE_LIMIT binding missing), or a secret header value was supplied but secret storage (KEK) is not ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"text/html":{"schema":{"type":"string"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/CreationLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/CreationPolicy"}}}},"security":[],"parameters":[{"$ref":"#/components/parameters/GateVersion"}]}},"/api/declarative/validate":{"post":{"tags":["Public and account"],"operationId":"pubValidateDeclarativeConfig","summary":"Check an odile.yaml config without changing anything","description":"Parses and validates a whole-project declarative config (gateway.project, gateway.apps[], gateway.alerts, gateway.approvers) and returns normalized config plus warnings, or a list of per-path errors. Pure validation: makes no Durable Object calls and changes nothing. Body: either the raw config as text/yaml (or any non-application/json content type) in the request body, or application/json {\"config\": \"<yaml or json text>\"} (a bare JSON object body with no top-level \"config\" key is itself treated as the config). The raw body is capped at 64 KB (MAX_CONFIG); over that it is rejected before parsing. Gated behind CONFIG_GATEWAY_UPGRADE (measured directly in code; this flag is not in the task's given table, but it is the only thing that 404s this route) - currently \"1\" in wrangler.toml, so the route is live.","x-gate-flag":"CONFIG_GATEWAY_UPGRADE","requestBody":{"required":true,"content":{"text/yaml":{"schema":{"type":"string"}},"application/json":{"schema":{"$ref":"#/components/schemas/PubDeclarativeConfigBody"}}}},"responses":{"200":{"description":"Config is valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubDeclarativeValidateOk"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Body exceeds 64 KB, is not valid JSON (when sent as application/json), or the config failed validation (e.g. an unknown key, a bad route rule, an out-of-range rate limit). Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PubDeclarativeValidateBad"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"CONFIG_GATEWAY_UPGRADE is not \"1\".","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[],"parameters":[{"$ref":"#/components/parameters/GateVersion"}]}},"/api/declarative/sync":{"post":{"tags":["Public and account"],"operationId":"pubSyncDeclarativeConfig","summary":"Apply an odile.yaml to a project, creating it if needed","description":"Validates the config exactly as /api/declarative/validate does, then drives it through this same Worker's own public API (so it is bound by the same per-IP creation limit, plan limits and admin audit log as any direct caller) to make a project match the file: creates the project if no project_id is given (gateway.project is then required), creates missing apps and approvers, and applies run mode, loop-breaker, learning and anomaly-guard plugin settings and alert webhook/threshold. It never revokes or deletes anything; an existing app whose routes or rate limit differ from the file is reported in 'drift' rather than changed. Authorization: Bearer <project admin key> is required once a project_id is supplied (from the header, or the project is addressed via project_id in the JSON body or ?project_id= query string). dry_run (JSON body dry_run:true, or ?dry_run=1/true) lists the steps that would run without making any of the underlying calls. Same 64 KB raw-body cap and content-type handling as validate. Gated behind CONFIG_GATEWAY_UPGRADE, live \"1\" (see note on /api/declarative/validate).","x-gate-flag":"CONFIG_GATEWAY_UPGRADE","parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string"},"description":"Existing project to sync (alternative to the JSON body's project_id)."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"string","enum":["1","true"]},"description":"List the steps without changing anything."},{"$ref":"#/components/parameters/GateVersion"}],"requestBody":{"required":true,"content":{"text/yaml":{"schema":{"type":"string"}},"application/json":{"schema":{"$ref":"#/components/schemas/PubDeclarativeSyncBody"}}}},"responses":{"200":{"description":"Synced (or, with dry_run, the steps that would run).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubDeclarativeSyncResult"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Body too large/invalid JSON, or the config itself has validation errors. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PubDeclarativeSyncResult"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"A project_id was given (or created) but the admin key is missing or wrong for a step that needs it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubDeclarativeSyncResult"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"A step the admin key is not allowed to perform.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubDeclarativeSyncResult"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"CONFIG_GATEWAY_UPGRADE is not \"1\", or a referenced project/app does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"A step conflicted with existing state (its own underlying status, surfaced as the sync's status).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubDeclarativeSyncResult"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"429":{"description":"A step hit a rate limit (e.g. project creation).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubDeclarativeSyncResult"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"500":{"description":"A step's own call failed with 500 (e.g. project creation: the new project's Durable Object did not initialize). Missing from an earlier pass: syncConfig()'s project-creation step calls this same worker's POST /api/projects and, on `!r.ok`, returns `{ ok:false, status:r.status, ... }`; index.js's sync handler then does `out.status>=400 && out.status<600 ? out.status : 400`, so any 4xx/5xx a called step returns, 500 included, is surfaced as-is rather than collapsed to 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubDeclarativeSyncResult"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"503":{"description":"A step's own call failed with 503 (e.g. project creation: CREATE_LIMIT binding missing, or a secret header value supplied with KEK not ready). Missing from an earlier pass, for the same reason as 500 above.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubDeclarativeSyncResult"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[]}},"/mcp":{"post":{"tags":["Public and account"],"operationId":"pubMcpCall","summary":"Odile Gate's hosted MCP server (Streamable HTTP, JSON-RPC 2.0)","description":"Stateless Streamable-HTTP MCP endpoint at https://gate.odilelabs.com/mcp. No install or separate connection key. Existing-project tools require a project key. Supports MCP 2026-07-28 plus legacy 2025-06-18/2025-03-26/2024-11-05. Modern requests are single JSON-RPC 2.0 messages with per-request protocolVersion and clientCapabilities in params._meta, matching MCP-Protocol-Version and Mcp-Method headers, and Mcp-Name for tools/call. server/discover is available to both eras and returns supportedVersions, tools capabilities, instructions, resultType:complete, serverInfo metadata and public cache hints (ttlMs:300000). Modern tools/list and tools/call need no initialize; every modern result includes resultType:complete and serverInfo metadata, and tools/list has the same public cache hints. Tools are ordered consistently and vary only with deployment flags. Modern initialize, notifications/initialized, ping and logging/setLevel are removed. Legacy initialize still negotiates only the original three versions (including fallback to 2025-06-18 for a 2025-11-25 request), and legacy ping, batches and notification acknowledgments retain their previous behavior. No Mcp-Session-Id is issued. Request body is capped at 64 KB and must be valid JSON. Every tool call re-enters this same Worker's own public HTTP API internally (so project creation limits, plan limits and the admin audit log see it exactly as a direct API call would), tagged with x-gate-via: mcp and the caller's real cf-connecting-ip. Tools served (from src/mcp.js TOOLS, always listed): gate_openshell_setup, gate_create_project, gate_create_app (undocumented alias gate_add_app still accepted), gate_update_app, gate_set_models, gate_list_apps, gate_check_setup, gate_metrics, gate_audit, gate_create_run, gate_set_app_runs, gate_set_response, gate_add_approver, gate_invite_member, gate_list_members, gate_revoke_member, gate_list_actions, gate_explain_refusal, gate_delegate_run, gate_learn_suggestions, gate_audit_proof, gate_audit_verify, gate_run_tree, gate_run_timeline, gate_rotate_app_key, gate_revoke_app, gate_revoke_run. Two further tools are added only when the worker's CONFIG_GATEWAY_UPGRADE flag is on (it is, live \"1\"): gate_validate_config, gate_sync_declarative. One more tool is added only when USAGE_ALERTS is on (it is off, live \"0\", so it is not currently listed): gate_set_usage_alert_email. Most tools that administer an existing project require project_id and admin_key in their arguments, which this endpoint forwards as an Authorization: Bearer header to the internal call; never accepts or stores those values beyond the single request. Optional profiles: /mcp/setup creates and configures (12–14 tools depending on the config-file flag); /mcp/oversight watches and manages runs (15 tools). Each has its own tools/list, instructions and server card at its URL + /server-card; capabilities unavailable on a profile are refused. Original tool names and verb-first aliases remain callable for offered capabilities. The /mcp compatibility catalog and text are unchanged.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubMcpRequest"}}}},"responses":{"200":{"description":"One JSON-RPC response; legacy batches return an array. Modern results include resultType and serverInfo metadata. Existing legacy response bodies are unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubMcpResponse"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"202":{"description":"Legacy-only notifications receive an empty acknowledgment. Modern removed notifications are rejected. Empty acknowledgment only: no job_id, status_url, Location or polling operation.","content":{},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Invalid JSON; or modern validation failure: -32600 for malformed requests/ids or batches, -32602 for missing required per-request metadata, -32020 for missing/mismatched/malformed standard headers, -32022 Unsupported protocol version with data.supported and data.requested. Legacy per-message invalid-request errors retain HTTP200. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PubMcpJsonRpcError"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Modern unknown or removed RPC method: JSON-RPC -32601 (Method not found). Legacy method-not-found errors retain HTTP200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubMcpJsonRpcError"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"413":{"description":"Request body exceeds 64 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubMcpJsonRpcError"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[],"parameters":[{"$ref":"#/components/parameters/GateVersion"}]},"get":{"tags":["Public and account"],"operationId":"pubMcpInfo","summary":"MCP endpoint probed with GET (no SSE stream)","description":"This server only answers JSON-RPC over POST; it does not open an SSE stream on GET. A GET with an Accept header containing text/html (a browser) 302-redirects to /#mcp on the site. Any other GET (a plain HTTP client, most MCP SDKs probing capabilities) gets 405 with an Allow: POST header. Any HTTP method other than GET/POST on this path also gets a bare 405 with Allow: POST (same route handler, app.all('/mcp', ...)).","responses":{"302":{"description":"Browser GET (Accept: text/html): redirected to the human docs.","headers":{"Location":{"schema":{"type":"string","enum":["/#mcp"]}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"405":{"description":"Non-browser GET, or any method other than GET/POST. These two cases have different bodies (checked in handleMcp): a non-browser GET gets a JSON body {\"error\":\"POST JSON-RPC messages to this URL\"}; any other method (PUT, DELETE, PATCH, HEAD, OPTIONS) gets `new Response(null, {status:405, headers:{allow:'POST'}})` -- no body and no content-type header at all, not JSON. The content schema below applies only to the non-browser-GET case.","headers":{"Allow":{"schema":{"type":"string","enum":["POST"]}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[],"parameters":[{"$ref":"#/components/parameters/GateVersion"}]}},"/x402/packs":{"post":{"tags":["Public and account"],"operationId":"pubBuyBearerPack","summary":"Buy a transferable 100,000-call voucher with x402 (USDC on Base)","description":"Sells a single-use, bearer (project-independent) voucher worth 100,000 extra Gate calls for USD 10 paid as USDC on Base via the x402 protocol (scheme 'exact'). First call with no X-PAYMENT/Payment-Signature header returns a 402 challenge (payment requirements plus a bazaar description) the client signs and retries with that header. A settled payment that was already used returns the previously issued voucher's id/state instead of re-minting one (idempotent on the payment hash). The response is 201 with the voucher string (gpk_..., shown once, never recoverable) plus its id, sku, call count and a status URL; redemption into a specific project happens at the admin-scoped POST /api/projects/{project_id}/packs/redeem (out of this fragment's scope). Routed to the Durable Object named 'bearer-packs' at /x402/bearer/buy; Gate strips every incoming x-gate-* header before forwarding and sets x-gate-pack-resource to the original request URL for the 402 challenge's resource field. Real request body is capped at 1 KB and must be {} or {\"sku\":\"calls_100k\"}. Code reads env.X402_BEARER_PACKS for this route (bearerPacksEnabled), not X402_PACKS (which gates the separate, already-project-scoped POST /api/projects/{project_id}/packs route). X402_BEARER_PACKS is live \"1\" in wrangler.toml, so this route is live; the task's supplied flag table lists X402_PACKS=\"0\" for 'the x402 flag', which is a different flag from the one actually gating this route - flagged under doubts.","x-gate-flag":"X402_BEARER_PACKS","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"sku":{"type":"string","const":"calls_100k"}}}}}},"responses":{"200":{"description":"This exact payment hash already finished minting a voucher on an earlier call (client retried the same signed payment after already receiving a voucher for it): returns only {id, state} of the existing voucher, not the voucher secret again. Verified in src/x402.js bearerPack(): `row = ledger.rows('SELECT * FROM bearer_packs WHERE payment_hash=?', ...)[0]; if (row) return json({ id: row.id, state: row.state })` -- json() defaults to status 200, so this is NOT folded into 201 as an earlier pass claimed.","content":{"application/json":{"schema":{"type":"object","required":["id","state"],"properties":{"id":{"type":"string","pattern":"^[0-9a-f]{16}$"},"state":{"type":"string","enum":["unspent","spent"]}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"201":{"description":"A new voucher was minted for a payment settled for the first time.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubBearerPackVoucher"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"202":{"description":"The facilitator's settlement for this payment is still pending (a concurrent/retried call is mid-settlement, or the facilitator's settle response itself came back ambiguous). Body {\"error\":\"Payment settlement pending; retry with the same X-PAYMENT. Do not send a new payment.\",\"pending\":true}. Verified: src/x402.js settlePack()'s pending() helper, reached through bearerPack()'s `if (!result.settlement) return json(result, response.status)` pass-through of the inner /x402/pay call's status. No pollable job or voucher exists yet: no job_id, status_url or Location. Retry this same POST with the identical payment; never submit a new payment to resolve pending settlement.","content":{"application/json":{"schema":{"type":"object","required":["error","pending"],"properties":{"error":{"type":"string"},"pending":{"type":"boolean","enum":[true]}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Body is not {} or {\"sku\":\"calls_100k\"}. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"Payment required (no/invalid payment proof yet) or the submitted payment proof failed its checks; body carries an x402 challenge plus PAYMENT-REQUIRED/X-Payment-Required headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubBearerPackChallenge"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"X402_BEARER_PACKS is not \"1\".","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"Either the settled on-chain transaction was already used for a different voucher (bearerPack(): `if (!row) return json({ error: 'Payment transaction already used.' }, 409)`), or this payment's authorization (payer+nonce) is already reserved by a concurrent request for a different project/payload (settlePack(): `if (prior.project_id !== b.project_id || prior.payload_hash !== payloadHash) return json({ error: 'Payment authorization already reserved for another request.' }, 409)`, reached the same pass-through path as the 202 case above).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"413":{"description":"Real request body exceeds 1 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"503":{"description":"x402 payment service unavailable, or the settlement receipt was too large to return (do not resend payment; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[],"parameters":[{"$ref":"#/components/parameters/GateVersion"}]}},"/x402/packs/{id}":{"get":{"tags":["Public and account"],"operationId":"pubGetBearerPackStatus","summary":"Read a bearer pack voucher's state","description":"Looks up a previously minted voucher by its id (not the voucher secret itself) and returns sku, calls, state (unspent/spent), issued_at and, once redeemed, spent_at. Routed to the same 'bearer-packs' Durable Object as POST /x402/packs. Same X402_BEARER_PACKS flag gate as POST /x402/packs (live \"1\").","x-gate-flag":"X402_BEARER_PACKS","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{16}$"},"description":"The voucher's id, as returned by POST /x402/packs (not the gpk_... voucher secret)."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Voucher state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubBearerPackStatus"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"X402_BEARER_PACKS is not \"1\", or no voucher has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[]}},"/share/{token}":{"get":{"tags":["Public and account"],"operationId":"pubShareAudit","summary":"Read-only shared audit page for one app","description":"Returns an HTML page (not JSON) listing one app's stored calls from the last 30 days: time, method, route template (query pins stripped), status, outcome and latency; no bodies, headers, query values, user tokens or IPs, and no other app's data. token is <project id>_<64 hex chars> (SHARE_TOKEN), created by the project-admin POST /api/projects/{project_id}/apps/{app_id}/share (out of scope). Looked up by a hash of the token against stored, unexpired, non-revoked shares; a project on the Free plan (no handoff/Pro entitlement) gets the same not-found response as an unknown or expired token, so existence of a share link is never disclosed to a guesser. Supports ?before=<audit row id> to page to older calls (newest first); the page shows a link to the next older page when more rows remain. The page is marked noindex,nofollow,noarchive and sent with a locked-down Content-Security-Policy and no-store, private, no-transform caching.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^p[0-9a-f]{24}_[0-9a-f]{64}$"},"description":"The share token from the admin 'create share link' response."},{"name":"before","in":"query","required":false,"schema":{"type":"string","pattern":"^[1-9][0-9]*$"},"description":"Page to calls older than this stored audit row id (newest-first paging). Missing from an earlier pass: project.js's sharedAudit() reads it with `c.req.query('before')` and, if present and not a positive integer matching this pattern (and representable as a JS safe integer), returns the same 404 as an unknown token rather than 400 -- verified by reading sharedAudit()'s own `if (before !== undefined && (!/^[1-9][0-9]*$/.test(before) || !Number.isSafeInteger(Number(before)))) return shareNotFound()`."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Shared audit page.","content":{"text/html":{"schema":{"type":"string"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Token is malformed, unknown, expired, revoked, or belongs to a Free-plan project (handoff share links are a Pro feature) -- or, missing from an earlier pass, ?before is present and is not a bare positive integer (same shareNotFound() response as a bad token).","content":{"text/plain":{"schema":{"type":"string"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[]}},"/.well-known/ai-catalog.json":{"get":{"tags":["Public and account"],"operationId":"pubAiCatalog","summary":"AI agent discovery catalog","description":"Advisory discovery document pointing agents at the MCP server card (urn:air:odilelabs.com:mcp:gate). When X402_PACKS is \"1\" it additionally lists a paid-call-pack path entry with x-payment-info (fixed USD 10) and a projectAdmin bearer security scheme describing the project-scoped, admin-authenticated POST /api/projects/{project_id}/packs route (that route itself is out of this fragment's scope: it is reached via the /api/projects/{project_id}/* -> /admin/* mapping). X402_PACKS is currently \"0\", so this deployment's response omits that paths/components block. Served with permissive CORS (GET only) and cached 5 minutes.","responses":{"200":{"description":"Discovery catalog.","headers":{"Cache-Control":{"schema":{"type":"string","enum":["public, max-age=300"]}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"}},"content":{"application/ai-catalog+json":{"schema":{"$ref":"#/components/schemas/PubAiCatalog"}}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[],"parameters":[{"$ref":"#/components/parameters/GateVersion"}]}},"/llms.txt":{"get":{"tags":["Public and account"],"operationId":"pubLlmsTxt","summary":"Plain-text product and API reference for LLMs/agents","description":"Always 200, text/plain, no auth. Static long-form documentation of the whole product (how it works, Gate Actions, loop breaker, model-key gateway, anomaly guard, per-user rules, MCP setup, plans, guides) with sections spliced in or wording changed based on live env flags read at request time: X402_PACKS (adds an extra-calls-via-x402 paragraph and rewords the Free/Pro limit lines when \"1\"; currently \"0\", so absent), PROOF_STATS (adds a line pointing at /proof.json when both PROOF_STATS and PROOF_PROJECT_ID are set; currently set, so present), X402_BEARER_PACKS (adds the bearer-voucher paragraph under Plans when \"1\"; currently \"1\", so present), CONFIG_GATEWAY_UPGRADE (appends the full declarative-config section when \"1\"; currently \"1\", so present), AWS_MARKETPLACE (appends AWS Marketplace guidance when \"1\"; currently \"1\", so present). The OpenShell section and the template list are always appended. The linked /llms-full.txt keeps extended model API, per-user and risk-score explanations; /llms.txt is the navigation index.","responses":{"200":{"description":"Plain-text reference document.","content":{"text/plain":{"schema":{"type":"string"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[],"parameters":[{"$ref":"#/components/parameters/GateVersion"}]}},"/demo-login/jwks.json":{"get":{"tags":["Public and account"],"operationId":"pubDemoLoginJwks","summary":"JWKS for Gate's demo per-user-rules login","description":"Returns the single Ed25519 (EdDSA) public key Gate's demo login issuer signs tokens with, so a project's per-user rules (user_tokens config) can be tried without a real identity provider. Honoured only on Demo Desk projects (upstream https://sandbox.gate.odilelabs.com), never on a project with a real upstream. Depends on a signing-key secret being configured in the deploy, not on one of the named feature flags; this task cannot measure a secret's presence from wrangler.toml vars, so whether the 503 case is live here is unconfirmed.","responses":{"200":{"description":"JWKS document.","headers":{"Cache-Control":{"schema":{"type":"string","enum":["public, max-age=300"]}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubDemoJwks"}}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"503":{"description":"Demo login's signing key is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[],"parameters":[{"$ref":"#/components/parameters/GateVersion"}]}},"/demo-login/token":{"get":{"tags":["Public and account"],"operationId":"pubDemoLoginToken","summary":"Issue a 10-minute demo login token for any user name","description":"Anyone can obtain a token for any user name; this is deliberate (the per-user-rules sandbox), which is why Gate only honours this issuer on Demo Desk projects. user must match 1-64 letters, digits or one of . _ @ | -. Token is an EdDSA JWT (iss https://gate.odilelabs.com/demo-login, aud gate-demo, sub = user), valid 600 seconds, sent back as both a bare string and the header name (x-odile-user-token) a caller should send it as.","parameters":[{"name":"user","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._@|-]{1,64}$"},"description":"Any user name to mint a demo token for."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Demo token issued.","headers":{"Cache-Control":{"schema":{"type":"string","enum":["no-store"]}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubDemoTokenResponse"}}}},"400":{"description":"user missing or does not match the allowed character set/length. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"503":{"description":"Demo login's signing key is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[]}},"/integrations/openshell/manifest.json":{"get":{"tags":["Public and account"],"operationId":"pubOpenshellManifest","summary":"OpenShell integration download manifest","description":"Always 200, no auth. Describes the native OpenShell v0.1.5 HTTP-request middleware integration (implementation/version info, the setup recipe text, and a hosting note that Gate only hosts these source downloads - it does not run a gRPC service), plus the list of downloadable files with their path, sha256 and a URL under /integrations/openshell/files/{name} (that files route is a static-file download, out of this fragment's scope per the task's exclusion rules). Served with cache-control: no-cache.","responses":{"200":{"description":"Manifest.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubOpenshellManifest"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[],"parameters":[{"$ref":"#/components/parameters/GateVersion"}]}},"/join/{token}":{"get":{"tags":["Public and account"],"operationId":"pubViewInvite","summary":"View a team-invite link","description":"Reachable directly from index.js (not through the toProject() /api/projects/{project_id}/* -> /admin/* mapping): index.js's own app.get/post('/join/:token', ...) forwards straight to the named project's Durable Object at /join/{token}, so this is a public, unauthenticated route. token is <project id>_<64 hex chars> (INVITE_TOKEN). Shows an HTML page with the invited member's name and role if the invite exists, is unexpired (72-hour TTL) and unaccepted/unrevoked; otherwise an HTML 'gone' page, 410. Viewing does not consume the invite.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^p[0-9a-f]{24}_[0-9a-f]{64}$"},"description":"The invite token from a project admin's POST /api/projects/{project_id}/members response (invite_url)."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Invite page.","content":{"text/html":{"schema":{"type":"string"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"410":{"description":"Token is malformed, unknown, expired, already accepted, revoked, or the project is blocked (e.g. an AWS Marketplace account-state refusal).","content":{"text/plain":{"schema":{"type":"string"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[]},"post":{"tags":["Public and account"],"operationId":"pubAcceptInvite","summary":"Accept a team-invite link","description":"Accepts the invite named by token and returns an HTML page showing the new member key (gm_...) exactly once; the key is never shown again. Requires the request to actually come from the invite page: Gate checks the Origin header against the x-gate-origin it set when proxying the page (or, for a same-origin no-referrer submission, the Sec-Fetch-Site: same-origin signal) and refuses with a plain-text 403 otherwise - a CSRF guard, not a documented API for scripted use. The member record is claimed with an atomic UPDATE ... WHERE accepted_at IS NULL AND revoked_at IS NULL AND invite_expires_at > now RETURNING id, so a concurrent accept/revoke/expiry can only let one caller win. Team size cap (10 members) is enforced at invite creation (POST /api/projects/{project_id}/members, out of scope), not here.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^p[0-9a-f]{24}_[0-9a-f]{64}$"},"description":"The invite token being accepted."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Invite accepted; page shows the member key once.","content":{"text/html":{"schema":{"type":"string"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Origin/Sec-Fetch-Site did not match an open of this same invite page.","content":{"text/plain":{"schema":{"type":"string"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"410":{"description":"Token malformed/unknown/expired/already accepted/revoked, or lost the race to claim it, or the project is blocked.","content":{"text/plain":{"schema":{"type":"string"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[]}},"/alerts/unsubscribe/{token}":{"get":{"tags":["Public and account"],"operationId":"pubViewUnsubscribe","summary":"Confirm-page for stopping usage-alert emails","description":"Reachable directly from index.js, like /join/{token}, not through the admin mapping. Gated twice behind USAGE_ALERTS: index.js itself 404s the route entirely when the flag is off, and the Durable Object handler repeats the same check (defence in depth / no behavioural trace of the feature when off). USAGE_ALERTS is currently \"0\", so this route 404s today regardless of token. When on, a valid, unused token (project's SHARE_TOKEN format, matched by hash against the stored unsubscribe-link hash) returns an HTML confirm page with a form posting to the same URL; otherwise plain-text 404.","x-gate-flag":"USAGE_ALERTS","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^p[0-9a-f]{24}_[0-9a-f]{64}$"},"description":"The unsubscribe token from a usage-alert email."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Confirm-unsubscribe page.","content":{"text/html":{"schema":{"type":"string"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Two different bodies depending on which check failed (checked in src/index.js and src/project.js): with USAGE_ALERTS \"0\" (the current live state), index.js itself answers before the project is even reached, as JSON `{\"error\":\"not found\"}` -- this is the actual response today. Only once USAGE_ALERTS is \"1\" does the request reach the project's own handler, which answers text/plain ('Share link not found.' for a malformed token via shareNotFound(), or 'Unsubscribe link not found or already used.' for a well-formed but unknown/already-used one). An earlier pass documented only the text/plain case, which is not what this deployment actually returns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"text/plain":{"schema":{"type":"string"}}},"x-gate-flag":"USAGE_ALERTS","headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[]},"post":{"tags":["Public and account"],"operationId":"pubConfirmUnsubscribe","summary":"Stop usage-alert emails for a project","description":"Clears the stored alert_email and its unsubscribe-hash for the project the token belongs to (alert_settings row), so no further gate.usage/plan-limit alert emails are sent until the owner sets an address again. Same double USAGE_ALERTS gate and token checks as the GET of this route; currently 404 live since USAGE_ALERTS is \"0\".","x-gate-flag":"USAGE_ALERTS","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^p[0-9a-f]{24}_[0-9a-f]{64}$"},"description":"The unsubscribe token from a usage-alert email."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Unsubscribed.","content":{"text/plain":{"schema":{"type":"string"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Same two cases and bodies as the GET of this route: with USAGE_ALERTS \"0\" (current live state) index.js answers application/json {\"error\":\"not found\"} before reaching the project; only with USAGE_ALERTS \"1\" does a bad/unknown token reach the project's text/plain response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}},"text/plain":{"schema":{"type":"string"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[]}},"/api/projects/{project_id}/project":{"get":{"tags":["Project admin"],"operationId":"projGetProject","summary":"Get the project summary","description":"Returns the project's id, name, upstream URL, configured upstream secret header name (never the value), whether a secret is sealed, plan, plan limits, this calendar month's call/app usage (with an `upgrade`/`checkout` hint once Free usage reaches 80%), extra-call billing status, pack balance fields when x402 packs (`X402_PACKS`) or bearer packs (`X402_BEARER_PACKS`) are enabled, a count of calls rejected for a missing/invalid key, and loop-breaker stats. Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Any accepted member key (viewer, approver or admin) may read this. A member-key caller's response additionally includes `member: {id, name, role}`.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]},{"memberKey":[]}],"responses":{"200":{"description":"Project summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjSummary"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing, invalid, or (member key) not accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found (the project id has never been initialized).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/members":{"get":{"tags":["Project admin"],"operationId":"projListMembers","summary":"List team members","description":"Lists the project's team members (owner key is not a member row) with id, name, role, state (`invited`, `active` or `revoked`), created_at and last_used_at. Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Owner only: a member key of any role gets 403 `member_role_forbidden`, even an admin-role member.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]}],"responses":{"200":{"description":"Member list.","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/ProjMember"}}},"required":["members"]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a member key; only the owner's admin key may list members.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}},"post":{"tags":["Project admin"],"operationId":"projInviteMember","summary":"Invite a team member","description":"Creates an invite for a new team member and returns a one-time invite link (`{origin}/join/{token}`), valid 72 hours; opening the link does not consume it, only accepting it does. Up to 10 active (non-revoked) members per project (409 `team_full` past that). Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Owner only: a member key of any role gets 403 `member_role_forbidden`, even an admin-role member.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjInviteMemberRequest"}}}},"responses":{"201":{"description":"Member invited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjInviteMemberResponse"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"name is missing, blank, over 60 characters, or contains control characters; or role is not viewer, approver or admin. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a member key; only the owner's admin key may invite members.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"`{\"error\":\"team_full\"}` (already at the 10-member cap), or (admin-key caller) the admin key was rotated during this call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/members/{member_id}/revoke":{"post":{"tags":["Project admin"],"operationId":"projRevokeMember","summary":"Revoke a team member","description":"Immediately revokes a member's key or pending invite; the member's accepted key and any pending invite hash are cleared. Idempotent: revoking an already-revoked member still returns 200. Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Owner only: a member key of any role gets 403 `member_role_forbidden`, even an admin-role member.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"member_id","in":"path","required":true,"schema":{"type":"string"},"description":"Member id, e.g. mem_xxxxxxxxxxxxxxxx."},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]}],"responses":{"200":{"description":"Revoked.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"revoked":{"type":"string"}},"required":["ok","revoked"]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a member key; only the owner's admin key may revoke members.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found, or no member exists with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/risk-model":{"put":{"tags":["Project admin"],"operationId":"projSetRiskModel","summary":"Install or remove the approval-risk scoring model","description":"Installs a version-1 JSON tree-ensemble model used to score held (approval-required) writes with an advisory `risk` (0-1) shown in the approvals queue; scores never approve, reject or execute anything. Body is the model JSON object, or JSON `null` to remove the installed model. Body capped at 512 KiB. A model must have version 1, the matching project_id, feature_names exactly equal to the shared risk feature list, a finite base_margin (|x| <= 1e6), and 1-100 trees, each node either a leaf `{leaf: <finite number>}` or a split `{feature, threshold, value, missing_left, left, right}` with feature one of the shared set, finite threshold/value, boolean missing_left, and maximum depth 4. Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). A member key needs role `admin` for this write; `viewer` and `approver` member keys get 403 `member_role_forbidden`.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]},{"memberKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjRiskModel"}}}},"responses":{"200":{"description":"Model installed or removed.","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Body is missing/over 512 KiB, not valid JSON, or fails model validation (version, project_id, feature_names, base_margin, tree count, or a tree node's shape/depth). Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a viewer or approver member key; only an admin-role member or the owner may set the risk model.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin key was rotated during this call; sign in with the current key and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/admin-key/rotate":{"post":{"tags":["Project admin"],"operationId":"projRotateAdminKey","summary":"Rotate the project's admin key","description":"Issues a new admin key for the project; the old admin key stops working immediately. The new key is returned once and never shown again. Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Owner only: a member key of any role gets 403 `member_role_forbidden`, even an admin-role member.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]}],"responses":{"200":{"description":"New admin key, shown once.","content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"type":"string"},"admin_key":{"type":"string"},"note":{"type":"string"}},"required":["project_id","admin_key","note"]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a member key; only the owner's admin key may rotate itself.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin key was already rotated by a concurrent call during this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/secret":{"put":{"tags":["Project admin"],"operationId":"projSetSecret","summary":"Set, replace or remove the sealed upstream secret header","description":"Seals the header Gate adds to every forwarded call to the project's upstream API (for example an `Authorization` bearer token or provider API key). Send `{header_name?, header_value}` to set it (header_name defaults to `Authorization`; header_value up to 4,096 characters, one line, and the header name may not be a reserved header or start with `cf-`, `x-forwarded-` or `x-gate-`), or `{\"header_value\": null}` to remove it. The value is sealed with the project's key-encryption key and is never returned or logged. Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). A member key needs role `admin` for this write; `viewer` and `approver` member keys get 403 `member_role_forbidden`.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]},{"memberKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjSetSecretRequest"}}}},"responses":{"200":{"description":"Secret updated.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"header_name":{"type":["string","null"]},"has_secret":{"type":"boolean"}},"required":["ok","header_name","has_secret"]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Body is not a JSON object with header_value, or the header name/value fails validation. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a viewer or approver member key; only an admin-role member or the owner may set the secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin key was rotated during this call; sign in with the current key and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"503":{"description":"Secret storage is not configured (GATE_KEK key-encryption key unavailable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/billing/checkout":{"post":{"tags":["Project admin"],"operationId":"projBillingCheckout","summary":"Start a Stripe Checkout session to upgrade to Pro","description":"Creates (or reuses) a Stripe customer for the project and starts a subscription Checkout session for the Pro plan, including the metered extra-calls price line item when one is configured. Returns the Checkout URL to redirect the owner to. Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Owner only: a member key of any role gets 403 `member_role_forbidden`, even an admin-role member.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]}],"responses":{"200":{"description":"Checkout session created.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a member key; only the owner's admin key may start checkout.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin key was rotated during this call (after a new Stripe customer was created).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"502":{"description":"Stripe could not be reached, or Stripe itself returned an error (the Stripe error message, or a generic 'Stripe answered <status>').","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"503":{"description":"Billing is not configured (no Pro Stripe price set), or Stripe returned an error (forwarded with Stripe's own status).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/billing/portal":{"post":{"tags":["Project admin"],"operationId":"projBillingPortal","summary":"Start a Stripe billing-portal session","description":"Creates a Stripe billing-portal session for the project's existing Stripe customer and returns its URL. The project must already have checked out once (have a Stripe customer); there is no billing account to manage before that. Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Owner only: a member key of any role gets 403 `member_role_forbidden`, even an admin-role member.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]}],"responses":{"200":{"description":"Portal session created.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"No Stripe customer yet; the project must upgrade to Pro (billing/checkout) first. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a member key; only the owner's admin key may open the billing portal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"502":{"description":"Stripe could not be reached, or Stripe itself returned an error (the Stripe error message, or a generic 'Stripe answered <status>').","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"503":{"description":"Stripe returned an error (forwarded with Stripe's own status).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/billing/extra":{"get":{"tags":["Project admin"],"operationId":"projGetBillingExtra","summary":"Get metered extra-call billing settings","description":"Reports whether metered extra-call billing is on for this project (Pro plan with a Stripe customer and a configured metered price), the configured `max_extra_millions` cap, the current month's extra calls used past the included quota, and calls already billed this month. When billing is not on, `why` explains why. Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Owner only: a member key of any role gets 403 `member_role_forbidden`, even an admin-role member.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]}],"responses":{"200":{"description":"Extra-call settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjExtraSettings"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a member key; only the owner's admin key may read billing settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}},"put":{"tags":["Project admin"],"operationId":"projSetBillingExtra","summary":"Set the metered extra-call cap","description":"Sets `max_extra_millions`, a whole number from 0 (stop forwarding calls once the included quota is used) to 100 (each unit = 1,000,000 calls at $10/million on Pro). Returns the updated extra-call settings (same shape as the GET). Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Owner only: a member key of any role gets 403 `member_role_forbidden`, even an admin-role member.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"max_extra_millions":{"type":"integer","minimum":0,"maximum":100}},"required":["max_extra_millions"]}}}},"responses":{"200":{"description":"Updated extra-call settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjExtraSettings"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"max_extra_millions is missing, not a whole number, or outside 0-100. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a member key; only the owner's admin key may change billing settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin key was rotated during this call; sign in with the current key and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/packs":{"get":{"tags":["Project admin"],"operationId":"projListPacks","summary":"List purchased call packs and the current pack balance","description":"Lists the project's purchased x402 100,000-call packs (id, sku, calls, remaining, paid_amount, network, payer, settlement_id, created_at) and the current pack balance (remaining_calls, and this month's plan allowance). Enabled only while `X402_PACKS` is on (currently `0`, so this route 404s today). Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Owner only: a member key of any role gets 403 `member_role_forbidden`, even an admin-role member.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]}],"x-gate-flag":"X402_PACKS","responses":{"200":{"description":"Packs and balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjPacksResponse"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a member key; only the owner's admin key may read packs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found, or X402_PACKS is off (feature not found).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}},"post":{"tags":["Project admin"],"operationId":"projBuyPack","summary":"Buy a 100,000-call pack with an x402 (USDC on Base) payment","description":"Pays for one 100,000-call pack (sku `calls_100k`, $10) with an x402 payment signature in the `X-Payment` (or `Payment-Signature`) header, on top of the normal admin/member authorization. Body is `{}` or `{\"sku\": \"calls_100k\"}`. Without a payment header this returns a 402 x402 payment challenge instead of an error. Enabled only while `X402_PACKS` is on (currently `0`). Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Owner only: a member key of any role gets 403 `member_role_forbidden`, even an admin-role member.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]}],"x-gate-flag":"X402_PACKS","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string","enum":["calls_100k"]}},"additionalProperties":false}}}},"responses":{"201":{"description":"Pack credited.","content":{"application/json":{"schema":{"type":"object","properties":{"pack":{"$ref":"#/components/schemas/ProjPack"},"remaining_calls":{"type":"integer"},"allowance":{"type":"object"}},"required":["pack"]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"202":{"description":"Payment settlement is pending; retry the same call with the identical X-Payment header. Do not send a new payment. No pollable job or voucher exists yet: no job_id, status_url or Location. Retry this same POST with the identical payment; never submit a new payment to resolve pending settlement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Body has a field other than sku, or sku is not calls_100k. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"x402 payment required/invalid: an x402 payment challenge (scheme, network, asset, payTo, amount) or an error explaining why the presented payment did not settle.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a member key; only the owner's admin key may buy packs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found, or X402_PACKS is off (feature not found).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"This payment authorization is already reserved for a different request, or the admin key was rotated during this call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"413":{"description":"Request body exceeds 1 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"503":{"description":"The x402 payment service (facilitator) is unavailable, so no payment challenge or settlement could be produced.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/packs/redeem":{"post":{"tags":["Project admin"],"operationId":"projRedeemPack","summary":"Redeem a transferable call-pack voucher","description":"Redeems a transferable 100,000-call voucher (bought via POST /x402/packs) into this project's pack balance. Body must be exactly `{\"voucher\": \"<voucher>\"}` (any other shape, including extra fields, returns 404, matching the worker edge's own gate on this route). Enabled only while `X402_BEARER_PACKS` is on; the task's listed env flags do not include it, but it is read from this checkout's wrangler.toml and is currently `1` (live). Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Owner only: a member key of any role gets 403 `member_role_forbidden`, even an admin-role member.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]}],"x-gate-flag":"X402_BEARER_PACKS","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"voucher":{"type":"string"}},"required":["voucher"],"additionalProperties":false}}}},"responses":{"200":{"description":"Pack credited.","content":{"application/json":{"schema":{"type":"object","properties":{"pack":{"$ref":"#/components/schemas/ProjPack"},"remaining_calls":{"type":"integer"},"allowance":{"type":"object"}},"required":["pack"]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a member key; only the owner's admin key may redeem packs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found, the body is not exactly {voucher}, X402_BEARER_PACKS is off, or redemption is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The voucher was already redeemed (includes spent_at), or the admin key was rotated during this call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"503":{"description":"The voucher's payment settled but the ledger response was missing its id/transaction/payer fields; redemption could not complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/alerts":{"get":{"tags":["Project admin"],"operationId":"projGetAlerts","summary":"Get webhook alert and idle-app settings","description":"Returns the configured alert webhook origin (full URL redacted to its origin), the refused-call spike threshold, the idle_days setting used to flag idle app keys, the last alert time, and the most recent 20 delivered/attempted alerts. Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Any accepted member key (viewer, approver or admin) may read this; only the owner's admin key or an admin-role member may write to it.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]},{"memberKey":[]}],"responses":{"200":{"description":"Alert settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjAlertSettings"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}},"put":{"tags":["Project admin"],"operationId":"projSetAlerts","summary":"Set webhook alert and idle-app settings","description":"Updates any of `webhook_url` (HTTPS webhook URL, or null to clear it; validated the same way as other Gate webhooks), `threshold` (whole number 5-1,000: refused calls in the alert window before a spike alert fires) and `idle_days` (whole number 1-90: days with no allowed call before an app key is flagged idle). Unset fields keep their current value. Returns the updated settings (same shape as the GET). Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). A member key needs role `admin` for this write; `viewer` and `approver` member keys get 403 `member_role_forbidden`.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]},{"memberKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjSetAlertsRequest"}}}},"responses":{"200":{"description":"Updated alert settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjAlertSettings"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Body is not a JSON object, threshold is outside 5-1,000, idle_days is outside 1-90, or webhook_url fails webhook validation. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a viewer or approver member key; only an admin-role member or the owner may change alert settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin key was rotated during this call; sign in with the current key and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/alerts/email":{"get":{"tags":["Project admin"],"operationId":"projGetAlertsEmail","summary":"Get the usage-alert email address","description":"Returns the owner's address for Free-plan usage-limit alert emails (null if unset). Dark feature: 404s unless `USAGE_ALERTS` is on (currently `0`, so this route 404s today). Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Owner only: a member key of any role gets 403 `member_role_forbidden`, even an admin-role member.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]}],"x-gate-flag":"USAGE_ALERTS","responses":{"200":{"description":"Alert email setting.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjAlertEmailSettings"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a member key; only the owner's admin key may read the alert email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found, or USAGE_ALERTS is off (feature not found).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}},"put":{"tags":["Project admin"],"operationId":"projSetAlertsEmail","summary":"Set or clear the usage-alert email address","description":"Sets `{\"alert_email\": \"you@example.com\"}` (validated email address) or clears it with `{\"alert_email\": null}`. Setting an address mints a sealed one-click unsubscribe token for it. The address itself is never written to the admin change log (redacted). Dark feature: 404s unless `USAGE_ALERTS` is on (currently `0`). Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Owner only: a member key of any role gets 403 `member_role_forbidden`, even an admin-role member.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]}],"x-gate-flag":"USAGE_ALERTS","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"alert_email":{"type":["string","null"],"format":"email"}},"required":["alert_email"]}}}},"responses":{"200":{"description":"Updated alert email setting.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjAlertEmailSettings"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Body is not {alert_email}, or alert_email is not a valid email address. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a member key; only the owner's admin key may change the alert email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found, or USAGE_ALERTS is off (feature not found).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin key was rotated during this call; sign in with the current key and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"503":{"description":"The unsubscribe link cannot be sealed (GATE_KEK not configured).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/owner-email":{"get":{"tags":["Project admin"],"operationId":"projGetOwnerEmail","summary":"Get the owner notification email address","description":"Reuses the same stored address and response shape as alerts/email, under the `OWNER_EMAIL` flag (currently `0`, so this route 404s today). The code gives no further distinct behavior from alerts/email beyond the flag it is gated on; I could not find a separate purpose for the two routes in this checkout. Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Owner only: a member key of any role gets 403 `member_role_forbidden`, even an admin-role member.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]}],"x-gate-flag":"OWNER_EMAIL","responses":{"200":{"description":"Owner email setting.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjAlertEmailSettings"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a member key; only the owner's admin key may read the owner email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found, or OWNER_EMAIL is off (feature not found).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}},"put":{"tags":["Project admin"],"operationId":"projSetOwnerEmail","summary":"Set or clear the owner notification email address","description":"Same request/response shape and validation as PUT alerts/email (it calls the identical handler), gated on `OWNER_EMAIL` instead of `USAGE_ALERTS` (currently `0`). Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Owner only: a member key of any role gets 403 `member_role_forbidden`, even an admin-role member.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]}],"x-gate-flag":"OWNER_EMAIL","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"alert_email":{"type":["string","null"],"format":"email"}},"required":["alert_email"]}}}},"responses":{"200":{"description":"Updated owner email setting.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjAlertEmailSettings"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Body is not {alert_email}, or alert_email is not a valid email address. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a member key; only the owner's admin key may change the owner email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found, or OWNER_EMAIL is off (feature not found).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin key was rotated during this call; sign in with the current key and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"503":{"description":"The unsubscribe link cannot be sealed (GATE_KEK not configured).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/enterprise":{"get":{"tags":["Project admin"],"operationId":"projGetEnterprise","summary":"Get enterprise controls","description":"Returns whether signed webhooks are configured, the IP allowlist, observe-only mode, the SIEM streaming target (origin only) and its delivery state, whether local audit storage is on, the per-user JWT verification config, and the configured request-blocking regex rules. Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Any accepted member key (viewer, approver or admin) may read this; only the owner's admin key or an admin-role member may write to it.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]},{"memberKey":[]}],"responses":{"200":{"description":"Enterprise settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjEnterpriseSettings"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}},"put":{"tags":["Project admin"],"operationId":"projSetEnterprise","summary":"Set enterprise controls","description":"Updates any subset of: `ip_allowlist` (up to 50 IPv4/IPv6 addresses or CIDR blocks); `observe_only` (boolean; report IP, user-scope, block-rule, model, tool, value-cap and loop violations instead of blocking them; key, allowed-route, run, body-size and quota checks still apply); `siem` (`null` to clear, or `{url, format: \"json\"|\"splunk_hec\", header_name?, header_value?}` where header_name/header_value must both be present or both absent, header_name matching `^[A-Za-z0-9-]{1,64}$` and header_value a non-empty string up to 500 characters); `store_audit` (boolean; refused to turn off unless a SIEM URL is already set or set in the same call, so the audit trail is never silently lost); `block_rules` (the literal string `\"basic\"` for the built-in SQL/prompt-override/path-traversal presets, or up to 20 `{label (<=60 chars), pattern (<=200 chars, no nested-repeat patterns like `(a+)+`), flags (\"\" or \"i\")}`, each pattern compiled and rejected if invalid); `user_tokens` (`null` to clear, or `{jwks_url, issuer, audience?, claim?}` for per-user route checks; the Gate demo-login issuer/JWKS is only accepted on a Demo Desk project whose upstream is the sandbox); and `rotate_signing_secret: true` (mints a new `whsec_...` signed-request secret, returned once in the response). Returns the updated settings, plus the new signing secret when rotated. Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). A member key needs role `admin` for this write; `viewer` and `approver` member keys get 403 `member_role_forbidden`.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]},{"memberKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjSetEnterpriseRequest"}}}},"responses":{"200":{"description":"Updated enterprise settings (plus signing_secret and a one-time note when rotated).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjEnterpriseSettings"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Body is not a JSON object, or one of ip_allowlist/observe_only/siem/store_audit/block_rules/user_tokens fails its own validation (see description). Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The caller is a viewer or approver member key; only an admin-role member or the owner may change enterprise settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin key was rotated during this call; sign in with the current key and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/setup-check":{"get":{"tags":["Project admin"],"operationId":"projSetupCheck","summary":"Check the project's Gate policy for common gaps (read-only)","description":"Inspects the project's configured policy only (no upstream calls, no settings changed, no gateway-call allowance used): observe-only mode, apps whose writes do not require a run, user-scoped routes with no user_tokens configured, apps with wildcard routes, and approval rules with no active approver. Optional `app` query parameter (an app id) scopes the check to one active app. Returns findings with a remediation call for each, a status (`configured`, `review` or `action_required`), and `verification: \"configuration_only\"` -- it is not a security certificate or runtime proof. Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Any accepted member key (viewer, approver or admin) may read this.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"app","in":"query","required":false,"schema":{"type":"string","pattern":"^app_[0-9a-f]{16}$"},"description":"Limit the check to one active app id."},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]},{"memberKey":[]}],"responses":{"200":{"description":"Setup-check report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjSetupCheck"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"app is present but not a valid app id. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found, or (with ?app=) no active app exists with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/metrics":{"get":{"tags":["Project admin"],"operationId":"projMetrics","summary":"Get operational metrics for the last 24 hours","description":"Stored call rows from the last 24 hours grouped by HTTP status and refusal reason, with average/max duration (measured through response headers, including upstream wait, not pure Gate overhead); this month's plan usage; per-app anomaly scores/drivers/24h counts; idle app keys (per the project's idle_days setting); and coverage notes. Coverage is partial (at most 20 stored rows per hour for invalid keys; local audit may have been disabled during part of the window) -- never a full traffic total or health certificate. Sends no upstream requests, changes no settings, and uses no gateway-call allowance. Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Any accepted member key (viewer, approver or admin) may read this.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]},{"memberKey":[]}],"responses":{"200":{"description":"Metrics report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjMetrics"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/changes":{"get":{"tags":["Project admin"],"operationId":"projChanges","summary":"Get the admin change log","description":"Returns the most recent 500 rows of the project's admin change log: every non-GET `/admin/*` and approver `/approve/*` call, with its action (`METHOD /path`, with ids normalized out of the path), target app/action id when matched, resulting HTTP status, caller IP (from `x-gate-ip`), truncated user agent, a before/after snapshot of the changed setting (each JSON-stringified and truncated to 2,000 characters; sensitive values such as the alert email are redacted before logging), and the acting member's id/name when the caller was a member key. Rows older than 365 days are swept. Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Any accepted member key (viewer, approver or admin) may read this.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]},{"memberKey":[]}],"responses":{"200":{"description":"Change-log rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjChangesResponse"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/pilot-report":{"get":{"tags":["Project admin"],"operationId":"projPilotReport","summary":"Get a pilot summary from the audit log","description":"Summarizes the audit log over a window of `days` (query parameter, whole number, clamped to 1-365, default 14 when omitted or not a number): total calls, a breakdown by outcome (`forwarded` for calls with no refusal reason, otherwise the refusal reason), and the top 10 app/route/reason combinations for loop-breaker activity, each marked `stopped` (loop_detected) or `would have stopped` (loop_observed, i.e. would have been caught had the loop breaker been stricter). Authorization: Bearer <admin key> (the project owner's key), or a team member key (`gm_...`). Any accepted member key (viewer, approver or admin) may read this.","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":365,"default":14},"description":"Lookback window in days; non-numeric or out-of-range values are clamped to 1-365, default 14."},{"$ref":"#/components/parameters/GateVersion"}],"security":[{"adminKey":[]},{"memberKey":[]}],"responses":{"200":{"description":"Pilot report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjPilotReport"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Admin key missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/apps":{"get":{"tags":["Apps"],"operationId":"appsListApps","summary":"List all apps in the project","description":"Returns every app ever created in the project (active and revoked), ordered by creation. For each app it computes: its masked key (`gk_<id>_...`, or null if no active key), its route rules as `METHOD /path` strings, its current model allow-list, effective loop-breaker settings (saved values, not strict-tightened), anomaly-guard config, whether it is suspended, its response-filter allow-list, client-handoff `expires_at`/`max_calls`/`calls_used` (Pro/internal only; null otherwise), and `idle_since` (set once the app has made no allowed call for the project's configured idle_days, default 14). Apps created from a template also carry `template`, `approval_routes` and `refused_routes`. GET is allowed for every member role, including viewer.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Apps in the project.","content":{"application/json":{"schema":{"type":"object","required":["apps"],"properties":{"apps":{"type":"array","items":{"$ref":"#/components/schemas/AppsApp"}}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}},"post":{"tags":["Apps"],"operationId":"appsCreateApp","summary":"Create a new app and issue its key","description":"Registers an app with a name, an allow-list of route rules (or a built-in template's rules), a per-minute rate limit, and optionally a model allow-list and client-handoff limits (Pro/internal plan only). Returns the new app plus its key, shown once -- Gate stores only its SHA-256 hash.\n\nRoute rule syntax (parseRule in guard.js), used both for the literal `routes` list and for a template's built-in rules: a rule is the string `METHOD /path` or `METHOD /path?key=value&...`. METHOD is one of GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, or `*` (any method). The path must start with `/`, be under 200 characters, and each /-separated segment must be one of: a literal (letters, digits, `. _ ~ -`; not `.` or `..`), a named param `:name` (`:` then a letter/underscore then up to 40 letters/digits/underscores), the literal placeholder `{user}` (matches only the signed-in user's id when per-user JWT rules are configured), or `*` as the LAST segment only (matches the rest of the path -- a glob glued onto a word, e.g. `/users*`, is rejected because it would also match sibling names like `/users-admin`). An optional query part pins required `?key=value` pairs (up to 5 pairs, keys matching `[A-Za-z0-9._~-]{1,64}`, non-empty values with no control characters), but is refused on `POST` and `*` rules, since an insert takes its owner from the body, not the query -- scope writes with `{user}` in the path instead. Up to 50 rules per app.\n\nBody fields: `name` (required, 1-80 chars, no control characters) is the app's display name, shown in the dashboard and audit log. `template` (optional) picks one of the built-in API templates (stripe, github, shopify, hubspot, supabase, slack, recall, quickbooks, xero) and uses its pre-defined rules, per-minute default, and (for display) its approval_routes/refused_routes metadata, UNLESS `routes` is also given, in which case the literal `routes` list is used instead; the template's `per_minute` default still applies, but in that case the app is NOT recorded as created from the template -- it carries no `template`/`approval_routes`/`refused_routes` metadata (createApp only writes the app_templates row when `useTemplate` is true, i.e. only when `routes` was NOT given alongside `template`). `routes` (required unless `template` is given without this field) is an array of 1-50 rule strings as above. `per_minute` (optional, whole number 1-6000, default 60 or the template's default) is the app's rate limit. `expires_at` (optional) must be a future ISO-8601 timestamp with a timezone offset, at most 30 days out; setting it (or `max_calls`) requires the Pro or internal plan. `max_calls` (optional, whole number 1-100,000) caps total calls for the app's key. `models` (optional) is an array of 1-50 model name strings (each an exact model name or a prefix ending in `*`), or `null` for no restriction; once set, a /g/... call asking for another model is refused before reaching the upstream.\n\nCreating the app is refused once the project is at its plan's active-app limit (Free: 3, Pro: 25, internal: 100); reaching that limit also triggers a usage-alert check on the Free plan.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppsCreateAppRequest"}}}},"responses":{"201":{"description":"App created.","content":{"application/json":{"schema":{"type":"object","required":["app","key","note"],"properties":{"app":{"$ref":"#/components/schemas/AppsApp"},"key":{"type":"string","description":"The app's bearer key for /g/... calls, format gk_<16-hex-id>_<base64url>. Shown only in this response."},"note":{"type":"string","const":"This key is shown once. Gate stores only its SHA-256 hash."}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Invalid name, template, routes, per_minute, expires_at, max_calls or models. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"templates":{"type":"array","items":{"type":"string"},"description":"Present only when template names an unknown slug: the list of valid slugs."},"rule":{"type":"string","description":"Present only on a bad route rule: the offending rule text (truncated to 200 chars)."}}}]},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"expires_at or max_calls was set, but the project is not on the Pro or internal plan. Also returned, with error aws_subscription_inactive, if this project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error","upgrade","message"],"properties":{"error":{"const":"pro_required"},"upgrade":{"type":"string","format":"uri"},"message":{"type":"string"}}},{"type":"object","required":["error","message"],"properties":{"error":{"const":"aws_subscription_inactive"},"message":{"type":"string"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"The project is at its plan's active-app limit.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error","limit","used","allowed","plan","upgrade","message"],"description":"Free plan.","properties":{"error":{"const":"plan_limit"},"limit":{"const":"apps"},"used":{"type":"integer"},"allowed":{"type":"integer"},"plan":{"const":"free"},"upgrade":{"type":"string","format":"uri"},"message":{"type":"string"}}},{"$ref":"#/components/schemas/Error"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin key (or member key) that authorized this call was rotated/revoked while the request was in flight; resend with the current key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/apps/{app_id}/revoke":{"post":{"tags":["Apps"],"operationId":"appsRevokeApp","summary":"Permanently revoke an app's key","description":"Revokes the app (sets revoked_at) and immediately revokes all of its keys. Irreversible -- unlike suspend/resume, a revoked app cannot be un-revoked, and the active-app count it freed is available for a new app. Member role must be admin.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Revoked.","content":{"application/json":{"schema":{"type":"object","required":["ok","revoked"],"properties":{"ok":{"const":true},"revoked":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Member role is not admin.","content":{"application/json":{"schema":{"type":"object","required":["error","role"],"properties":{"error":{"const":"member_role_forbidden"},"role":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"no active app with that id"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/apps/{app_id}/rotate":{"post":{"tags":["Apps"],"operationId":"appsRotateApp","summary":"Rotate an app's key","description":"Issues a brand-new key for the app and revokes the old one at once -- there is no overlap window; the old key stops working the instant this call succeeds. The new key is shown once (Gate stores only its hash).","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Rotated.","content":{"application/json":{"schema":{"type":"object","required":["app_id","key","note"],"properties":{"app_id":{"type":"string"},"key":{"type":"string"},"note":{"type":"string","const":"The old key stopped working just now. This key is shown once."}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Member role is not admin.","content":{"application/json":{"schema":{"type":"object","required":["error","role"],"properties":{"error":{"const":"member_role_forbidden"},"role":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"no active app with that id"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin/member key that authorized this call changed while it was in flight.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/apps/{app_id}/share":{"post":{"tags":["Apps"],"operationId":"appsCreateShare","summary":"Create (or replace) a client-handoff read-only audit share link","description":"Pro/internal plan only. Creates a read-only link ({SITE}/share/<token>) that shows, with no sign-in, only this app's own calls from the last 30 days (time, method, route template, status, outcome, latency -- no bodies, headers, query strings, user tokens, IPs or other apps' data). The token is 256 random bits; Gate stores only its SHA-256 hash. Creating a new link for the same app replaces any existing one.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"expires_at":{"type":"string","format":"date-time","description":"Future ISO-8601 timestamp with timezone, at most 30 days out. Omit for a link that never expires."}}}}}},"responses":{"201":{"description":"Share link created.","content":{"application/json":{"schema":{"type":"object","required":["url","expires_at"],"properties":{"url":{"type":"string","format":"uri"},"expires_at":{"type":["string","null"],"format":"date-time"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Body was not JSON, had extra keys, or expires_at was not a valid future timestamp within 30 days. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"Project is not on the Pro or internal plan. Also returned, with error aws_subscription_inactive, if this project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error","upgrade","message"],"properties":{"error":{"const":"pro_required"},"upgrade":{"type":"string","format":"uri"},"message":{"type":"string"}}},{"type":"object","required":["error","message"],"properties":{"error":{"const":"aws_subscription_inactive"},"message":{"type":"string"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Member role is not admin.","content":{"application/json":{"schema":{"type":"object","required":["error","role"],"properties":{"error":{"const":"member_role_forbidden"},"role":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"no active app with that id"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin/member key that authorized this call changed while it was in flight.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}},"delete":{"tags":["Apps"],"operationId":"appsRevokeShare","summary":"Revoke an app's client-handoff share link","description":"Pro/internal plan only (checked before deleting). Deletes the app's share-link row if one exists; always answers {ok:true} even if the app has no link or does not exist -- there is no app-existence check and no admin-key staleness check on this route.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Revoked (or there was nothing to revoke).","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"Project is not on the Pro or internal plan. Also returned, with error aws_subscription_inactive, if this project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error","upgrade","message"],"properties":{"error":{"const":"pro_required"},"upgrade":{"type":"string","format":"uri"},"message":{"type":"string"}}},{"type":"object","required":["error","message"],"properties":{"error":{"const":"aws_subscription_inactive"},"message":{"type":"string"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Member role is not admin.","content":{"application/json":{"schema":{"type":"object","required":["error","role"],"properties":{"error":{"const":"member_role_forbidden"},"role":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/apps/{app_id}/loop":{"get":{"tags":["Apps"],"operationId":"appsGetLoop","summary":"Read an app's loop-breaker settings","description":"The loop breaker refuses a call (HTTP 429, x-odile-gate-loop-detected: true) before it reaches the upstream or uses quota, once the same call (method + path-hash + query + body-hash) repeats `repeats` times inside `window_seconds` (counted per call, even with other calls in between), or from the 5th identical call when the last four gaps between them average under 250 ms with under 15 ms of spread. The 429 names the rule that stopped it: header x-odile-gate-loop-rule and body `rule` (repeat_count or machine_cadence), with `identical_calls`. Returns the saved settings plus the currently `effective` ones: while the app's anomaly guard holds it in a strict_until window, the effective policy is tightened to at most 3 repeats and at least a 10-second window, regardless of the saved values. GET is allowed for any member role. machine_cadence is always on as well: 5 identical calls arriving under 250 ms apart with under 15 ms of jitter are stopped before the count is reached. sweep (route sweep) counts calls to one route rule with any ids, pages, query strings or bodies: at sweep.calls inside sweep.window_seconds (default 100 in 600 s; apps created through POST /apps start in mode block, older apps without a saved mode and Machine Access connection apps in alert) Gate sends one gate.route_sweep webhook and an audit row; mode block also refuses further calls to that route (429, x-gate-refused: route_sweep) until the window ends; off disables it.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Loop settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppsLoopStatus","properties":{"machine_cadence":{"type":"object","properties":{"identical_calls":{"type":"integer"},"gap_under_ms":{"type":"integer"},"jitter_under_ms":{"type":"integer"}}},"sweep":{"type":"object","properties":{"calls":{"type":"integer","minimum":10,"maximum":100000},"window_seconds":{"type":"integer","minimum":10,"maximum":3600},"mode":{"type":"string","enum":["alert","block","off"]}}}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"app not found"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}},"put":{"tags":["Apps"],"operationId":"appsSetLoop","summary":"Change an app's loop-breaker thresholds","description":"Either field defaults to the app's current saved value when omitted, so {} is a no-op (still re-saved and re-logged). Clears the project's in-memory loop-state cache for this app so the new thresholds take effect on the next call. Optional sweep {calls 10-100000, window_seconds 10-3600, mode alert|block|off} sets the route-sweep rule; the answer echoes sweep when it was sent.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppsLoopUpdateRequest","properties":{"sweep":{"type":"object","properties":{"calls":{"type":"integer","minimum":10,"maximum":100000},"window_seconds":{"type":"integer","minimum":10,"maximum":3600},"mode":{"type":"string","enum":["alert","block","off"]}}}}}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["app_id","repeats","window_seconds"],"properties":{"app_id":{"type":"string"},"repeats":{"type":"integer"},"window_seconds":{"type":"integer"},"sweep":{"type":"object","description":"Echoed when the request sent sweep.","required":["calls","window_seconds","mode"],"properties":{"calls":{"type":"integer"},"window_seconds":{"type":"integer"},"mode":{"type":"string","enum":["alert","block","off"]}}}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"repeats or window_seconds out of range, or sweep is not an object of calls, window_seconds and mode within range. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Member role is not admin.","content":{"application/json":{"schema":{"type":"object","required":["error","role"],"properties":{"error":{"const":"member_role_forbidden"},"role":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"app not found"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin/member key that authorized this call changed while it was in flight.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/apps/{app_id}/anomaly":{"get":{"tags":["Apps"],"operationId":"appsGetAnomaly","summary":"Read an app's anomaly-guard configuration","description":"The anomaly guard scores an app's per-UTC-minute traffic after 30 minutes of history (calls/minute, refused ratio, upstream-429 ratio, identical-repeat ratio) against an exponentially-weighted baseline. strict_until (read-only) is included only while a guard-opened strict window is still in the future. GET is allowed for any member role.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Anomaly settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppsAnomalyStatus"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"app not found"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}},"put":{"tags":["Apps"],"operationId":"appsSetAnomaly","summary":"Change an app's anomaly-guard settings","description":"Any field omitted keeps the app's current value; an unknown key is rejected. mode: off (no scoring), alert (default -- writes an audit event and sends a gate.anomaly webhook when configured, 1-per-app-per-hour cooldown shared with the refused-call spike alert), or strict (also tightens the loop breaker for 30 minutes, then restores the configured loop setting). The score never blocks calls by itself. Changing half_life discards the running baseline (fresh start) rather than mixing decay rates; changing any other field resets only the current anomaly streak. Switching away from strict ends any currently-open strict window early.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppsAnomalyUpdateRequest"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppsAnomalyStatus"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unknown key, or mode/z_threshold/min_minutes/half_life out of range. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Member role is not admin.","content":{"application/json":{"schema":{"type":"object","required":["error","role"],"properties":{"error":{"const":"member_role_forbidden"},"role":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"app not found"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin/member key that authorized this call changed while it was in flight.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/apps/{app_id}/response":{"put":{"tags":["Apps"],"operationId":"appsSetResponseFilter","summary":"Set (or clear) an app's response-field allow-list","description":"Optional response projection: when allow is a non-empty array, only the JSON Pointer-style paths listed (up to 32 paths, each up to 16 segments / 256 characters; * matches one segment of any name; selecting a container keeps its whole subtree) are kept in the upstream's JSON response before it reaches the app; everything else is dropped. allow: null turns filtering off. This is explicit projection, not PII detection, and only applies to a JSON response body.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["allow"],"properties":{"allow":{"oneOf":[{"type":"null","description":"No filtering: full upstream response passes through."},{"type":"array","minItems":1,"maxItems":32,"items":{"type":"string","maxLength":256,"pattern":"^/"},"description":"JSON Pointer-style paths (up to 16 /-separated segments each); * matches one segment of any name; selecting a container keeps its whole subtree."},{"type":"null"}]}}}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["app_id","response"],"properties":{"app_id":{"type":"string"},"response":{"type":"object","required":["allow"],"properties":{"allow":{"oneOf":[{"type":"null","description":"No filtering: full upstream response passes through."},{"type":"array","minItems":1,"maxItems":32,"items":{"type":"string","maxLength":256,"pattern":"^/"},"description":"JSON Pointer-style paths (up to 16 /-separated segments each); * matches one segment of any name; selecting a container keeps its whole subtree."},{"type":"null"}]}}}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"allow was not null or a valid array of JSON Pointer paths. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Member role is not admin.","content":{"application/json":{"schema":{"type":"object","required":["error","role"],"properties":{"error":{"const":"member_role_forbidden"},"role":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"no active app with that id"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin/member key that authorized this call changed while it was in flight.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/apps/{app_id}/models":{"put":{"tags":["Apps"],"operationId":"appsSetModels","summary":"Set (or clear) an app's model allow-list","description":"For apps gating an AI model API: models must be an array of 1-50 model name strings, each an exact name or a prefix ending in * (e.g. gpt-4.1-mini, claude-haiku-*), or null to remove any restriction. Duplicates are silently deduplicated. Once set, a /g/... call asking for any other model (checked in the JSON body's model field including each line of a JSON-Lines batch, a form/multipart model field, a ?model= query parameter, or a /models/<name> path segment) is refused with 403 before the provider sees it; a body Gate cannot parse as strict UTF-8 JSON is refused the same way. Bumps the app's policy version so the change takes effect immediately on the gateway.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["models"],"properties":{"models":{"oneOf":[{"type":"null","description":"No model restriction."},{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","minLength":1,"maxLength":101,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,99}\\*?$"},"description":"Exact model names, or a prefix ending in '*'. Duplicates are silently removed."},{"type":"null"}]}}}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["app_id","models"],"properties":{"app_id":{"type":"string"},"models":{"oneOf":[{"type":"null","description":"No model restriction."},{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","minLength":1,"maxLength":101,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,99}\\*?$"},"description":"Exact model names, or a prefix ending in '*'. Duplicates are silently removed."},{"type":"null"}]}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"models key missing, or not a valid list/null. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Member role is not admin.","content":{"application/json":{"schema":{"type":"object","required":["error","role"],"properties":{"error":{"const":"member_role_forbidden"},"role":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"no active app with that id"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin/member key that authorized this call changed while it was in flight.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/apps/{app_id}/caps":{"put":{"tags":["Apps"],"operationId":"appsSetCaps","summary":"Set (or clear) an app's value caps","description":"Caps a number inside a call, enforced by Gate rather than the agent's prompt: e.g. a refund agent may refund at most 5000 cents alone. caps is a list of 1-20 {route, field, max, over} or null to remove them. Gate reads every value the call gives the field: the query string and a JSON or form body, including every duplicate and differently cased key. A call matching a capped route that sends a value over max, leaves the field out (APIs often default to the whole amount; a Stripe refund with no amount refunds the full charge), or gives a value that is not a plain number or a body Gate cannot read (not strict UTF-8, JSON that does not parse, a form body that is also JSON, or a content type other than application/json, +json or application/x-www-form-urlencoded) is refused with 403 over_cap, or, with over: hold, held for an approver with 202 approval_required and sent only when resent unchanged after approval. The route also covers its case, trailing-slash and double-slash spellings. A field path with * may match nothing. observe_only reports cap_observed instead. Bumps the app's policy version so the change takes effect immediately on the gateway.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["caps"],"properties":{"caps":{"oneOf":[{"type":"null","description":"No caps."},{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["route","field","max"],"properties":{"route":{"type":"string","description":"METHOD /path rule, as in routes (e.g. POST /refunds, POST /charges/:id/refund); no query part."},"field":{"type":"string","description":"Dotted path to the number in the call (amount, refund.amount); a * segment (not the first) means every array element or object value (items.*.price). Form keys in bracket form (refund[amount]) match too."},"max":{"type":"number","description":"The highest allowed value, in the API's own units (5000 for $50.00 in cents)."},"over":{"type":"string","enum":["refuse","hold"],"default":"refuse","description":"refuse: 403 over_cap. hold: the call waits sealed for an approver, as an approval action; needs an active approver."}}}}]}}}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["app_id","caps"],"properties":{"app_id":{"type":"string"},"caps":{"oneOf":[{"type":"null","description":"No caps."},{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["route","field","max"],"properties":{"route":{"type":"string","description":"METHOD /path rule, as in routes (e.g. POST /refunds, POST /charges/:id/refund); no query part."},"field":{"type":"string","description":"Dotted path to the number in the call (amount, refund.amount); a * segment (not the first) means every array element or object value (items.*.price). Form keys in bracket form (refund[amount]) match too."},"max":{"type":"number","description":"The highest allowed value, in the API's own units (5000 for $50.00 in cents)."},"over":{"type":"string","enum":["refuse","hold"],"default":"refuse","description":"refuse: 403 over_cap. hold: the call waits sealed for an approver, as an approval action; needs an active approver."}}}}]}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"caps key missing, or not a valid list/null. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Member role is not admin.","content":{"application/json":{"schema":{"type":"object","required":["error","role"],"properties":{"error":{"const":"member_role_forbidden"},"role":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"no active app with that id"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"A hold cap was set while the project has no active approver, or the admin/member key that authorized this call changed while it was in flight.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/apps/{app_id}/tools":{"put":{"tags":["Apps"],"operationId":"appsSetTools","summary":"Set (or clear) an app's MCP tool allow-list","description":"For apps that reach an MCP server through Gate: tools must be an array of 1-100 tool name strings, each an exact name or a prefix ending in * (e.g. get_weather, github_*), or null to remove any restriction. Duplicates are silently deduplicated. Once set, a /g/... POST whose JSON-RPC body is a tools/call for any other tool is refused with 403 tool_not_allowed before the MCP server sees it. Every message of a batch is checked, and so is every duplicate or differently cased method, params and name key; a body Gate cannot parse as strict UTF-8 JSON, or a tools/call with no readable name, is refused the same way. Other methods (initialize, tools/list, resources and prompts) pass, and tools/list responses are not filtered. Bumps the app's policy version so the change takes effect immediately on the gateway.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tools"],"properties":{"tools":{"oneOf":[{"type":"null","description":"No tool restriction."},{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1,"maxLength":129,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.:/-]{0,127}\\*?$"},"description":"Exact tool names, or a prefix ending in '*'. Duplicates are silently removed."},{"type":"null"}]}}}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["app_id","tools"],"properties":{"app_id":{"type":"string"},"tools":{"oneOf":[{"type":"null","description":"No tool restriction."},{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1,"maxLength":129,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.:/-]{0,127}\\*?$"},"description":"Exact tool names, or a prefix ending in '*'. Duplicates are silently removed."},{"type":"null"}]}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"tools key missing, or not a valid list/null. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Member role is not admin.","content":{"application/json":{"schema":{"type":"object","required":["error","role"],"properties":{"error":{"const":"member_role_forbidden"},"role":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"no active app with that id"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin/member key that authorized this call changed while it was in flight.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/apps/{app_id}/signing":{"get":{"tags":["Apps"],"operationId":"appsGetSigning","summary":"Read an app's signed-request status","description":"Signed agent requests: when enabled, Gate signs each outgoing call for this app with an Ed25519 key so the receiving site can verify it came from Gate (the public half is published to a shared signing directory). key is the current active key's kid and creation time, or null if signing was never enabled. retiring lists any key(s) still inside their rotation overlap window. GET is allowed for any member role; enabled is always false and key always null on a Gate deployment where SIGNED_REQUESTS is off, since PUT cannot turn it on there.","security":[{"adminKey":[]},{"memberKey":[]}],"x-gate-flag":"SIGNED_REQUESTS","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Signing status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppsSigningStatus"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"no active app with that id"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}},"put":{"tags":["Apps"],"operationId":"appsSetSigning","summary":"Turn signed requests on or off for an app","description":"{\"enabled\": true} is refused with 400 unless this Gate deployment has SIGNED_REQUESTS=\"1\" (live value on gate.odilelabs.com today: \"0\", i.e. dark -- every enable attempt currently fails this check). When enabling: Gate reuses the app's existing active signing key if it has one, otherwise generates a new Ed25519 keypair, seals the private half under GATE_KEK (503 if the KEK is not configured) and (re)publishes the public half to the shared signing directory (502 if that publish fails, in which case signing is NOT enabled). Turning it off just flips the stored flag; existing keys are left alone.","security":[{"adminKey":[]},{"memberKey":[]}],"x-gate-flag":"SIGNED_REQUESTS","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppsSigningStatus"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"enabled was missing/not boolean, or true while SIGNED_REQUESTS is off on this deployment. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Member role is not admin.","content":{"application/json":{"schema":{"type":"object","required":["error","role"],"properties":{"error":{"const":"member_role_forbidden"},"role":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"no active app with that id"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin/member key that authorized this call changed while it was in flight.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"502":{"description":"The new or rotated public key could not be published to the shared signing directory; signing was NOT enabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"503":{"description":"GATE_KEK is not configured on this deployment, so no signing key can be sealed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/apps/{app_id}/signing/rotate":{"post":{"tags":["Apps"],"operationId":"appsRotateSigningKey","summary":"Rotate an app's active signing key","description":"Generates a new Ed25519 key, publishes BOTH the old key (marked retiring, with a retire_at after the fixed rotation-overlap window) and the new key (marked active) to the shared signing directory before touching any local row, so a failed publish leaves the old key fully active and no local state changed. Refused with 409 if the app has no active signing key yet (enable signing first via PUT .../signing).","security":[{"adminKey":[]},{"memberKey":[]}],"x-gate-flag":"SIGNED_REQUESTS","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Rotated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppsSigningStatus"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Member role is not admin.","content":{"application/json":{"schema":{"type":"object","required":["error","role"],"properties":{"error":{"const":"member_role_forbidden"},"role":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"no active app with that id"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"Either the admin/member key changed mid-call, or (same status, different message) the app has no active signing key to rotate yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"502":{"description":"The rotation could not be published to the shared signing directory; the old key is still active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"503":{"description":"GATE_KEK is not configured on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/apps/{app_id}/learn":{"get":{"tags":["Apps"],"operationId":"appsLearnSuggestions","summary":"Read an app's learning-mode suggestions","description":"Returns the app's current learning session (if any) and whatever route templates it has inferred from that app's own authenticated (including authenticated-but-refused) traffic while learning was open. Each observed call is reduced to a method + normalized path template (id-like segments collapse to :id; a raw path containing :, * or { is never learned at all, since it could not have come from real traffic) -- no raw ids, query values, headers or bodies are kept, capped at 500 templates, and deleted automatically 7 days after the session ends. per_minute is a suggested rate limit: 2x the p99 of per-minute call counts observed, clamped to 10-6000. This read does NOT require the app to still be active (only that it exists at all).","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Learning state and suggestions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppsLearning"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No app with that id exists at all (revoked apps still answer 200).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"no app with that id"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}},"put":{"tags":["Apps"],"operationId":"appsSetLearning","summary":"Start, extend or stop an app's learning window","description":"minutes (default 60, 0 to 1440) opens (or re-opens/extends) a learning window of that length from now; a new window clears any templates/minute-counts collected by a previous one for this app. minutes: 0 ends the window immediately (clamping it to end now if it was still open) without clearing already-collected templates -- they still age out automatically 7 days after the (now-earlier) end. Returns the same shape as GET.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"minutes":{"type":"integer","minimum":0,"maximum":1440,"default":60,"description":"0 stops learning now; up to 1440 (24 hours)."}}}}}},"responses":{"200":{"description":"Learning window updated; body is the current learning/suggestions state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppsLearning"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Body missing or minutes out of 0-1440. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Member role is not admin.","content":{"application/json":{"schema":{"type":"object","required":["error","role"],"properties":{"error":{"const":"member_role_forbidden"},"role":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"no active app with that id"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin/member key that authorized this call changed while it was in flight.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/apps/{app_id}/learn/apply":{"post":{"tags":["Apps"],"operationId":"appsApplyLearning","summary":"Apply an app's learned route suggestions to its live allow-list","description":"Requires explicit confirmation. mode: \"extend\" (default) adds any suggested route not already on the app; mode: \"replace\" deletes all of the app's current routes first, then inserts the suggested ones. Either way the app's per_minute is set to the suggestion's computed value. Does not itself start or stop learning, and is refused if there are no suggested routes to apply. Bumps the app's policy version so the new allow-list takes effect immediately.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirm"],"properties":{"confirm":{"type":"boolean","const":true,"description":"Must be literally true."},"mode":{"type":"string","enum":["extend","replace"],"default":"extend"}}}}}},"responses":{"200":{"description":"Applied.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AppsLearning"},{"type":"object","required":["applied","mode"],"properties":{"applied":{"const":true},"mode":{"type":"string","enum":["extend","replace"]}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"confirm was not true, or mode was neither extend nor replace. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Member role is not admin.","content":{"application/json":{"schema":{"type":"object","required":["error","role"],"properties":{"error":{"const":"member_role_forbidden"},"role":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"no active app with that id"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"Either the admin/member key changed mid-call, or (same status, different message) there are no learning suggestions to apply.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/apps/{app_id}/suspend":{"post":{"tags":["Apps"],"operationId":"appsSuspendApp","summary":"Suspend an app (reversible)","description":"Marks the app suspended so its key is refused at the gateway; unlike revoke, the key works again as soon as the app is resumed. Optional reason (any string, stored truncated to 200 characters) is recorded for the audit log. Re-suspending an already-suspended app just updates the timestamp/reason.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"Suspended.","content":{"application/json":{"schema":{"type":"object","required":["app_id","suspended"],"properties":{"app_id":{"type":"string"},"suspended":{"const":true}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Member role is not admin.","content":{"application/json":{"schema":{"type":"object","required":["error","role"],"properties":{"error":{"const":"member_role_forbidden"},"role":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"App not found.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"app not found"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin/member key that authorized this call changed while it was in flight.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/apps/{app_id}/resume":{"post":{"tags":["Apps"],"operationId":"appsResumeApp","summary":"Resume a suspended app","description":"Clears the app's suspended state so its existing key works again. The request body, if any, is read but ignored (resume does not record a reason). Resuming an app that was not suspended is a no-op success.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Resumed.","content":{"application/json":{"schema":{"type":"object","required":["app_id","suspended"],"properties":{"app_id":{"type":"string"},"suspended":{"const":false}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Member role is not admin.","content":{"application/json":{"schema":{"type":"object","required":["error","role"],"properties":{"error":{"const":"member_role_forbidden"},"role":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"App not found.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"app not found"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin/member key that authorized this call changed while it was in flight.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/apps/{app_id}/runs":{"put":{"tags":["Apps"],"operationId":"appsSetRunMode","summary":"Set whether an app must call through a Gate Actions run","description":"mode: off (apps created before 17 Nov 2026, template apps and apps created with runs: \"off\" -- the app may call any of its allowed routes directly, except a call that a live run holds for approval: that call needs a run token, 403 run_required otherwise), writes (the default for a new app: every write call, i.e. a method other than GET/HEAD/OPTIONS, must carry a valid x-odile-run token naming an action the run permits; reads are unrestricted) or all (every call, including reads, must be inside a valid run). Bumps the app's policy version only when the mode actually changes.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["off","writes","all"]}}}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["app_id","mode"],"properties":{"app_id":{"type":"string"},"mode":{"type":"string","enum":["off","writes","all"]}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"mode was not one of off, writes, all. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Missing/invalid admin key or member key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project's AWS Marketplace subscription is inactive.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"aws_subscription_inactive"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Member role is not admin.","content":{"application/json":{"schema":{"type":"object","required":["error","role"],"properties":{"error":{"const":"member_role_forbidden"},"role":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"no active app with that id"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin/member key that authorized this call changed while it was in flight.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/runs":{"post":{"tags":["Actions, approvals and audit"],"operationId":"runsCreateRun","summary":"Create a run","description":"Grants one app a narrowed, time-limited permission slice: a list of \"METHOD /path\" actions (each optionally capped, held for approval, or given a GET recovery check), bound scope values, a ttl (60-86400s, 5s minimum for a sandbox upstream) and an optional max_calls (1-100000) and label. The app must be active. If any action requires approval, the project needs at least one active approver (standalone or an accepted approver-role member) or the run is refused. The run token is returned once as plain text; Gate stores only its SHA-256 hash. Writing a run with an admin key must have no await between the admin-key check and the insert, so a key rotated mid-request cannot still grant a run (409 admin_changed).","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"201":{"description":"Run created.","content":{"application/json":{"schema":{"type":"object","properties":{"run":{"$ref":"#/components/schemas/RunsRun"},"token":{"type":"string","description":"Shown once; send as the x-odile-run header alongside the app key.","example":"gr_0123456789abcdef_..."},"note":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Validation failed: app must be an app id (app_...); scope must be an object of up to 10 lowercase names (not \"user\") each 1-200 chars of . _ ~ -; actions must list 1-50 items, each a valid rule (optionally with a valid check, and idempotent only alongside check, and never check+approval together); ttl_seconds out of 60-86400 (5-86400 for a sandbox upstream); max_calls out of 1-100000. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No admin key and no accepted, unrevoked member key (gm_...) with authorization: Bearer <key>.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project was registered through AWS Marketplace (flag x-gate-flag AWS_MARKETPLACE, live value \"1\") and that subscription is now inactive (aws_subscription_inactive). Every /admin, /approve and /g route on the project refuses with this until the subscription is reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"member_role_forbidden: the signed-in member's role (viewer or, for a write, admin-only/approver-only routes, the wrong one of admin/approver) may not call this route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Either no active app with that id, or project not found (the project_id does not match any project ever created in this Durable Object).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"Either {error: 'add an approver before granting approval actions'} (an action needs approval but the project has none active), or the stale-admin-key case described above.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["app","actions"],"properties":{"app":{"type":"string","pattern":"^app_[0-9a-f]{16}$"},"scope":{"type":"object","additionalProperties":{"type":"string"},"description":"Up to 10 names (^[a-z][a-z0-9_]{0,30}$, not \"user\"), each value 1-200 chars of letters/digits/._~-."},"actions":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/RunsActionSpec"}},"ttl_seconds":{"type":"integer","minimum":5,"maximum":86400,"default":3600,"description":"Minimum is 60 unless the project's upstream is a sandbox target, then 5."},"max_calls":{"type":["integer","null"],"minimum":1,"maximum":100000},"label":{"type":["string","null"],"maxLength":120}}}}}}},"get":{"tags":["Actions, approvals and audit"],"operationId":"runsListRuns","summary":"List runs","description":"The project's 100 most recent runs, newest first, each with its live state (active/revoked/expired/invalid) computed from its own and its ancestors' revocation/expiry.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Up to 100 runs.","content":{"application/json":{"schema":{"type":"object","properties":{"runs":{"type":"array","items":{"$ref":"#/components/schemas/RunsRunListItem"}}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No admin key and no accepted, unrevoked member key (gm_...) with authorization: Bearer <key>.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project was registered through AWS Marketplace (flag x-gate-flag AWS_MARKETPLACE, live value \"1\") and that subscription is now inactive (aws_subscription_inactive). Every /admin, /approve and /g route on the project refuses with this until the subscription is reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"project not found (the project_id does not match any project ever created in this Durable Object -- checked before the admin/approve key is).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/runs/{run_id}/tree":{"get":{"tags":["Actions, approvals and audit"],"operationId":"runsGetRunTree","summary":"Get a run's delegation tree","description":"The named run plus every run delegated from it (recursively, to depth 5), each with its own live state.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{16}$"},"description":"Run id."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"The run tree.","content":{"application/json":{"schema":{"type":"object","properties":{"runs":{"type":"array","items":{"$ref":"#/components/schemas/RunsRunTreeItem"}}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No admin key and no accepted, unrevoked member key (gm_...) with authorization: Bearer <key>.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project was registered through AWS Marketplace (flag x-gate-flag AWS_MARKETPLACE, live value \"1\") and that subscription is now inactive (aws_subscription_inactive). Every /admin, /approve and /g route on the project refuses with this until the subscription is reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Either no run with that id, or project not found (the project_id does not match any project ever created in this Durable Object).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/runs/{run_id}/timeline":{"get":{"tags":["Actions, approvals and audit"],"operationId":"runsGetRunTimeline","summary":"Get a run's audit timeline","description":"Up to 500 audit events for this run (gateway calls, recoveries, approval decisions), newest first as stored and returned oldest-to-newest, plus the runs delegated directly from it. Page further back with ?before=<audit row id> (the oldest event id returned, when truncated).","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{16}$"},"description":"Run id."},{"name":"before","in":"query","required":false,"schema":{"type":"string","pattern":"^[1-9][0-9]*$"},"description":"An audit row id; returns events strictly before it."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Timeline page.","content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"string"},"audit_enabled":{"type":"boolean","description":"The project's store_audit Enterprise setting."},"events":{"type":"array","items":{"$ref":"#/components/schemas/RunsTimelineEvent"}},"children":{"type":"array","items":{"$ref":"#/components/schemas/RunsTimelineChild"}},"before":{"type":["integer","null"],"description":"Pass as ?before= to page further back, or null when this is the oldest page."}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"before must be an audit row id Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No admin key and no accepted, unrevoked member key (gm_...) with authorization: Bearer <key>.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project was registered through AWS Marketplace (flag x-gate-flag AWS_MARKETPLACE, live value \"1\") and that subscription is now inactive (aws_subscription_inactive). Every /admin, /approve and /g route on the project refuses with this until the subscription is reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Either no run with that id, or project not found (the project_id does not match any project ever created in this Durable Object).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/runs/{run_id}/revoke":{"post":{"tags":["Actions, approvals and audit"],"operationId":"runsRevokeRun","summary":"Revoke a run","description":"Marks the run revoked at once; its own and every delegated run's state becomes revoked. Admin-role only (not approver-role members).","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{16}$"},"description":"Run id."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Revoked.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"revoked":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No admin key and no accepted, unrevoked member key (gm_...) with authorization: Bearer <key>.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project was registered through AWS Marketplace (flag x-gate-flag AWS_MARKETPLACE, live value \"1\") and that subscription is now inactive (aws_subscription_inactive). Every /admin, /approve and /g route on the project refuses with this until the subscription is reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"member_role_forbidden: the signed-in member's role (viewer or, for a write, admin-only/approver-only routes, the wrong one of admin/approver) may not call this route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Either no active run with that id, or project not found (the project_id does not match any project ever created in this Durable Object).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/actions":{"get":{"tags":["Actions, approvals and audit"],"operationId":"runsListActions","summary":"List held/decided actions","description":"Up to 50 actions (filtered to ?state= when it is 1-12 lowercase letters, e.g. pending/approved/rejected/expired/executing/unknown; any other value is ignored and the newest 50 across all states are returned). When ?state=pending and the project has a risk model, rows are ordered by descending risk instead of recency. Expires any pending actions past their 24h TTL first.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"state","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-z]{1,12}$"}},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Up to 50 actions.","content":{"application/json":{"schema":{"type":"object","properties":{"actions":{"type":"array","items":{"$ref":"#/components/schemas/RunsAction"}}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No admin key and no accepted, unrevoked member key (gm_...) with authorization: Bearer <key>.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project was registered through AWS Marketplace (flag x-gate-flag AWS_MARKETPLACE, live value \"1\") and that subscription is now inactive (aws_subscription_inactive). Every /admin, /approve and /g route on the project refuses with this until the subscription is reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"project not found (the project_id does not match any project ever created in this Durable Object -- checked before the admin/approve key is).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/actions/{action_id}/{decision}":{"post":{"tags":["Actions, approvals and audit"],"operationId":"runsDecideAction","summary":"Decide a held action","description":"approve/reject need the action pending; reopen (the approver's word that they checked the upstream API and the call did not actually run) needs it unknown or executing and a note, and lets it execute once more. Only an active approver can decide: an approver key (gp_...), or a member key whose role is approver (accepted and not revoked) -- a bare project admin key, or an admin-role member, is refused with 403 even though it reaches this route, so revoking the last approver can never hand their decisions back to the run-granting admin. Rejecting also clears the action's sealed path/body. Logged to the audit chain as approval_approved/approval_rejected/approval_reopened. On this admin-path alias use an approver-role gm_ member key only. Dedicated gp_ approvers use the /approvals/actions path. The owner key authenticates but cannot decide.","security":[{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"action_id","in":"path","required":true,"schema":{"type":"string","pattern":"^act_[0-9a-f]{16}$"},"description":"Action id."},{"name":"decision","in":"path","required":true,"schema":{"type":"string","enum":["approve","reject","reopen"]},"description":"approve/reject need the action pending; reopen needs it unknown or executing and a note."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Decided.","content":{"application/json":{"schema":{"type":"object","properties":{"action_id":{"type":"string"},"state":{"type":"string","enum":["approved","rejected"]},"decided_by":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"reopen needs a note saying what you checked (it can run the call a second time) Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No active approver identity: {error: 'approver key missing or not accepted'} (an approver key was revoked between middleware and the handler), or the admin-key/member middleware's 401 described above.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project was registered through AWS Marketplace (flag x-gate-flag AWS_MARKETPLACE, live value \"1\") and that subscription is now inactive (aws_subscription_inactive). Every /admin, /approve and /g route on the project refuses with this until the subscription is reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Either member_role_forbidden (member role is not approver), {error: 'the app is no longer active'} (app revoked or suspended and the action had no run), or {error: 'approve, reject or reopen with an active approver key (dashboard sign-in with gp_...)'} when no approver identity is present at all (a bare admin key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Either no action with that id, or project not found (the project_id does not match any project ever created in this Durable Object).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The state-mismatch error: {error: 'the action is <state>; <decision> needs it <allowed states>'}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":300,"description":"Control characters are stripped; required for reopen."}}}}}},"x-gate-member-roles":["approver"]}},"/api/projects/{project_id}/approvers":{"post":{"tags":["Actions, approvals and audit"],"operationId":"runsCreateApprover","summary":"Create an approver","description":"Issues a new standalone approver key (gp_...), shown once (Gate stores only its SHA-256 hash). Admin-role only. A project caps at 25 active approvers.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"approver":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"key":{"type":"string","example":"gp_..."},"note":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"name is required (1 to 80 characters): who approves, e.g. \"Dana (support lead)\" Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No admin key and no accepted, unrevoked member key (gm_...) with authorization: Bearer <key>.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project was registered through AWS Marketplace (flag x-gate-flag AWS_MARKETPLACE, live value \"1\") and that subscription is now inactive (aws_subscription_inactive). Every /admin, /approve and /g route on the project refuses with this until the subscription is reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"Either member_role_forbidden, or {error: 'a project can have 25 active approvers'}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"project not found (the project_id does not match any project ever created in this Durable Object -- checked before the admin/approve key is).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"The admin key that authorized this call stopped being current (rotated/revoked) before the write landed: {error: 'the admin key changed during this call; sign in with the current key'}. (A deciding member's own key going stale mid-call is a 401 'admin key missing or not accepted', not this 409 -- see 401 above.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":80}}}}}}},"get":{"tags":["Actions, approvals and audit"],"operationId":"runsListApprovers","summary":"List approvers","description":"Every standalone approver ever created for the project (active and revoked), oldest first.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Approvers.","content":{"application/json":{"schema":{"type":"object","properties":{"approvers":{"type":"array","items":{"$ref":"#/components/schemas/RunsApprover"}}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No admin key and no accepted, unrevoked member key (gm_...) with authorization: Bearer <key>.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project was registered through AWS Marketplace (flag x-gate-flag AWS_MARKETPLACE, live value \"1\") and that subscription is now inactive (aws_subscription_inactive). Every /admin, /approve and /g route on the project refuses with this until the subscription is reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"project not found (the project_id does not match any project ever created in this Durable Object -- checked before the admin/approve key is).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/approvers/{approver_id}/revoke":{"post":{"tags":["Actions, approvals and audit"],"operationId":"runsRevokeApprover","summary":"Revoke an approver","description":"Revokes a standalone approver key at once; it stops being accepted on both /admin and /approve (and the approvals mirror). Admin-role only. Approval decisions it already made are untouched.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"approver_id","in":"path","required":true,"schema":{"type":"string"},"description":"Approver id, from POST /approvers."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Revoked.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"revoked":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No admin key and no accepted, unrevoked member key (gm_...) with authorization: Bearer <key>.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project was registered through AWS Marketplace (flag x-gate-flag AWS_MARKETPLACE, live value \"1\") and that subscription is now inactive (aws_subscription_inactive). Every /admin, /approve and /g route on the project refuses with this until the subscription is reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"member_role_forbidden: the signed-in member's role (viewer or, for a write, admin-only/approver-only routes, the wrong one of admin/approver) may not call this route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Either no active approver with that id, or project not found (the project_id does not match any project ever created in this Durable Object).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/audit":{"get":{"tags":["Actions, approvals and audit"],"operationId":"runsGetAudit","summary":"List audit rows","description":"Up to 200 most recent audit rows, optionally filtered by app id, a 3-digit status, and/or an up-to-16-letter method; an invalid filter value is simply ignored rather than erroring. duration_ms is the time Gate waited on the upstream: until its response headers arrived, or until Gate gave up (upstream_timeout); it is 0 for refused calls, which never reach the upstream, and for Demo Desk, the built-in sandbox, which answers inside Gate. route is the allowed rule a call matched; a call that matched none has an empty route, and segment holds only its path's first segment (for a one-segment path such as /admin, that segment is the whole path). Each exported row (JSON and CSV) also carries duration_source, computed on export: upstream, in_process (Demo Desk) or not_sent (Gate answered without calling the upstream).","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"app","in":"query","required":false,"schema":{"type":"string"},"description":"Exact app_id match."},{"name":"status","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{3}$"}},{"name":"method","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z]{1,16}$"},"description":"Matched case-insensitively (uppercased before the query)."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Audit rows.","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/RunsAuditRow"}}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No admin key and no accepted, unrevoked member key (gm_...) with authorization: Bearer <key>.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project was registered through AWS Marketplace (flag x-gate-flag AWS_MARKETPLACE, live value \"1\") and that subscription is now inactive (aws_subscription_inactive). Every /admin, /approve and /g route on the project refuses with this until the subscription is reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"project not found (the project_id does not match any project ever created in this Durable Object -- checked before the admin/approve key is).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/audit/proof":{"get":{"tags":["Actions, approvals and audit"],"operationId":"runsGetAuditProof","summary":"Export a signed audit proof","description":"A hash-chained, HMAC-signed export of audit rows from ?from= to ?to= (default: the whole retained range), up to 10,000 rows per call (page with the returned next_from), plus a page of decided-action outcome labels after ?actions_after= (an action id from a previous next_actions_after; page with next_actions_after). When the project's Enterprise store_audit setting is off, returns {enabled: false, note} instead and nothing else below applies.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"from","in":"query","required":false,"schema":{"type":"string","pattern":"^[1-9][0-9]*$"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","pattern":"^[1-9][0-9]*$"}},{"name":"actions_after","in":"query","required":false,"schema":{"type":"string","pattern":"^act_[0-9a-f]{16}$"}},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Either the signed proof, or {enabled: false, note} when store_audit is off.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RunsAuditProof"},{"type":"object","properties":{"enabled":{"type":"boolean","enum":[false]},"note":{"type":"string"}}}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Either 'from and to must be positive audit row ids in ascending order', or 'actions_after must be an action id from next_actions_after', or (cursor no longer retained) 'action cursor no longer retained; start a new export'. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No admin key and no accepted, unrevoked member key (gm_...) with authorization: Bearer <key>.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project was registered through AWS Marketplace (flag x-gate-flag AWS_MARKETPLACE, live value \"1\") and that subscription is now inactive (aws_subscription_inactive). Every /admin, /approve and /g route on the project refuses with this until the subscription is reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"project not found (the project_id does not match any project ever created in this Durable Object -- checked before the admin/approve key is).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"503":{"description":"audit signing is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/audit/verify":{"post":{"tags":["Actions, approvals and audit"],"operationId":"runsVerifyAudit","summary":"Verify a signed audit proof","description":"Re-checks a previously exported RunsAuditProof's hash chain and HMAC signature for this project and reports where it broke, if it did. The signed export is the body; {\"export\": <export>} is accepted too.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Verification result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunsAuditVerifyResult"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"send a version 1 signed export for this project (at most 10,000 rows): the body failed to parse as JSON, or did not match the expected shape (version/project_id/rows/previous_chain/head/signature). Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No admin key and no accepted, unrevoked member key (gm_...) with authorization: Bearer <key>.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project was registered through AWS Marketplace (flag x-gate-flag AWS_MARKETPLACE, live value \"1\") and that subscription is now inactive (aws_subscription_inactive). Every /admin, /approve and /g route on the project refuses with this until the subscription is reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"project not found (the project_id does not match any project ever created in this Durable Object -- checked before the admin/approve key is).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunsAuditProof"}}}}}},"/api/projects/{project_id}/audit.csv":{"get":{"tags":["Actions, approvals and audit"],"operationId":"runsExportAuditCsv","summary":"Download audit rows as CSV","description":"The newest 10,000 audit rows (no paging yet) as a CSV attachment (gate-audit.csv): time plus the same columns as GET /audit except id/at themselves (time replaces at). A cell starting with = + - @ or a tab/CR is prefixed with a quote to defuse spreadsheet formula injection.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"CSV file.","content":{"text/csv":{"schema":{"type":"string"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No admin key and no accepted, unrevoked member key (gm_...) with authorization: Bearer <key>.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project was registered through AWS Marketplace (flag x-gate-flag AWS_MARKETPLACE, live value \"1\") and that subscription is now inactive (aws_subscription_inactive). Every /admin, /approve and /g route on the project refuses with this until the subscription is reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"project not found (the project_id does not match any project ever created in this Durable Object -- checked before the admin/approve key is).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/api/projects/{project_id}/approvals/project":{"get":{"tags":["Actions, approvals and audit"],"operationId":"runsApproverGetProject","summary":"Get the approver's project view","description":"The project's name and the caller's own display name, for an approver dashboard sign-in. With phone approvals available, also phone_calls (true when Gate can phone an approver) and phone (\"saved\" or null) for the caller.","security":[{"approverKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"approver":{"type":"string"},"phone_calls":{"type":"boolean"},"phone":{"type":["string","null"],"enum":["saved",null]}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No accepted approver key (gp_...) and no accepted, unrevoked member key, with authorization: Bearer <key>.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project was registered through AWS Marketplace (flag x-gate-flag AWS_MARKETPLACE, live value \"1\") and that subscription is now inactive (aws_subscription_inactive). Every /admin, /approve and /g route on the project refuses with this until the subscription is reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"x-gate-member-roles":["viewer","approver","admin"]}},"/api/projects/{project_id}/approvals/actions":{"get":{"tags":["Actions, approvals and audit"],"operationId":"runsApproverListActions","summary":"List held/decided actions (approver view)","description":"Identical to GET /api/projects/{project_id}/actions, reachable with an approver key instead of an admin/member key.","security":[{"approverKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"state","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-z]{1,12}$"}},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Up to 50 actions.","content":{"application/json":{"schema":{"type":"object","properties":{"actions":{"type":"array","items":{"$ref":"#/components/schemas/RunsAction"}}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No accepted approver key (gp_...) and no accepted, unrevoked member key, with authorization: Bearer <key>.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project was registered through AWS Marketplace (flag x-gate-flag AWS_MARKETPLACE, live value \"1\") and that subscription is now inactive (aws_subscription_inactive). Every /admin, /approve and /g route on the project refuses with this until the subscription is reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"x-gate-member-roles":["viewer","approver","admin"]}},"/api/projects/{project_id}/approvals/actions/{action_id}/{decision}":{"post":{"tags":["Actions, approvals and audit"],"operationId":"runsApproverDecideAction","summary":"Decide a held action (approver view)","description":"Identical to POST /api/projects/{project_id}/actions/{action_id}/{decision}, reachable with an approver key instead of an admin/member key. A member key used here must still have the approver role.","security":[{"approverKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"action_id","in":"path","required":true,"schema":{"type":"string","pattern":"^act_[0-9a-f]{16}$"},"description":"Action id."},{"name":"decision","in":"path","required":true,"schema":{"type":"string","enum":["approve","reject","reopen"]},"description":"approve/reject need the action pending; reopen needs it unknown or executing and a note."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Decided.","content":{"application/json":{"schema":{"type":"object","properties":{"action_id":{"type":"string"},"state":{"type":"string","enum":["approved","rejected"]},"decided_by":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"reopen needs a note saying what you checked (it can run the call a second time) Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No accepted approver key (gp_...) and no accepted, unrevoked member key, with authorization: Bearer <key>.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"402":{"description":"This project was registered through AWS Marketplace (flag x-gate-flag AWS_MARKETPLACE, live value \"1\") and that subscription is now inactive (aws_subscription_inactive). Every /admin, /approve and /g route on the project refuses with this until the subscription is reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"member_role_forbidden: the signed-in member's role (viewer or, for a write, admin-only/approver-only routes, the wrong one of admin/approver) may not call this route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Either no action with that id, or project not found (the project_id does not match any project ever created in this Durable Object).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"409":{"description":"the action is <state>; <decision> needs it <allowed states>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":300}}}}}},"x-gate-member-roles":["approver"]}},"/g/{project_id}/{path}":{"get":{"tags":["Gateway"],"operationId":"gwProxyGet","summary":"Proxy a GET read through Gate to the project's upstream API.","description":"Forwards one call to the project's own upstream API through its allow-list, exactly as the app key's rules permit. This is the one route every Gate app actually calls; everything else in the API manages the project. The {path} segment (which may contain further slashes and a query string) is appended to the project's configured upstream base URL unchanged, except for `/_gate/run`, `/_gate/run/delegate`, `/_gate/actions/{id}` and `/_gate/recover`, which Gate intercepts itself and never forwards (out of scope here; see the Gate Actions/recovery fragment, except for the outcome_unknown recovery flow below, which this fragment documents because it is reached through this same proxy path).\n\nAuth: `Authorization: Bearer <app key>` (gw_... is wrong; app keys match APP_KEY) is required on every call. `x-odile-run` (a Gate Actions run token) is additionally required when the app's run mode is `all`, or `writes` and the method is a write (anything but GET/HEAD/OPTIONS), and is always required on `POST .../_gate/recover`. When a run token is sent, the call must match one of the run's granted actions (and every ancestor run's, for a delegated run) or it is refused with action_not_in_run.\n\nRequest headers Gate reads: `authorization` (the app key), `x-odile-run` (run token), `x-odile-action` (resumes a call that was held for approval, with the action id returned by the 202), `x-odile-user-token` (a signed-in user's JWT, for a route with a {user} or ?key={user} placeholder; needs user_tokens configured on the project or a 403), and `idempotency-key` (required on a write made inside a run, and on `POST .../_gate/recover`, up to 255 characters; a repeat of the same key on the same run gets already_executed or outcome_unknown instead of being resent). Gate also reads `content-length` to pre-check the 10 MB body cap. `x-gate-ip` and `x-gate-country` are set internally by the public worker from the real connecting IP/CF country and are not something a caller sets; any `x-gate-*` header a caller sends is deleted before this Durable Object ever sees it.\n\nHeaders dropped before the call reaches the upstream: hop-by-hop headers (connection, keep-alive, proxy-connection, proxy-authenticate, proxy-authorization, te, trailer, transfer-encoding, upgrade) and anything the client listed in its own Connection header, plus authorization, cookie, host, content-length, expect, forwarded, x-real-ip, true-client-ip, x-http-method-override/x-http-method/x-method-override, x-original-url/x-rewrite-url/x-original-uri/x-original-method, x-odile-user-token, x-odile-run, x-odile-action, and every cf-*, x-forwarded-* and x-gate-* header. The project's own upstream secret header (if configured) is injected here instead. Response headers dropped on the way back: the same hop-by-hop set plus set-cookie (one Gate host serves every project, so an upstream's cookie must never reach another project's caller).\n\nChecks run in this order, each able to refuse the call (reason is the `x-gate-refused` header and the JSON `error` field, both from the GwRefusal values below, unless noted): the project exists (project_not_found, 404, no refusal header, not logged) and is not an inactive AWS Marketplace subscription (aws_subscription_inactive, 402, no `x-gate-refused` header and no audit row at all -- checked again right before the upstream send) -> the app key (bad_key, 401; only the first 20 bad-key calls an hour get an audit row) -> a Pro client-handoff key's expiry/call cap (key_expired 401 / call_limit_reached 429) -> the app is not suspended (app_suspended, 403) -> the caller's IP against the project's allow-list (ip_not_allowed, 403, unless the project is in observe mode, which logs and forwards instead) -> the path has no encoded slash/backslash/dot-segment/control character (unsafe_path, 400) -> the app's own route allow-list and template (route_not_allowed, 403, for a template-refused route or no matching allow-list rule) -> a per-user route's x-odile-user-token (user_tokens_off 403 if the project has none configured; bad_user_token 401 if missing/invalid/expired; outside_user_scope 403 if it names a different user) -> the 10 MB body cap (body_too_large, 413) -> a _method field in the query or in a form, multipart or JSON body (method_override, 403, even when observing: Rails, Laravel and Symfony APIs would run that method instead of the one Gate checked) -> the project's regex block rules over the path, query and whole decoded body (blocked_by_rule, 403, unless observing) -> an app-level model allow-list, read out of the body/query/content-type (model_not_allowed, 403, also on an unreadable body, unless observing) -> the x-odile-run token, if the app's run mode requires one (run_required, 403) or one was sent (bad_run 401 if unknown/other app; run_revoked/run_expired 403 if the run or an ancestor is no longer active; action_not_in_run 403 if this method+path is not one of the run's granted actions, listing the ones that are) -> approval requirements, templated or set on the run action: with no x-odile-action header, the call is held (see 202 below) once its body fits the 1 MB approval cap (approval_body_too_large, 413, otherwise) and carries every field the template requires (required_field_missing, 400); with one, the action must exist (bad_action 403), be approved (approval_pending 409 / approval_rejected 403 / approval_expired 403 / already_executed 409 with its outcome / outcome_unknown 409 if it is mid-flight or unresolved), and match this exact call's method, path+query and forwarded headers and body hash (approval_mismatch, 409) -> a run write's Idempotency-Key (idempotency_key_required 400; already_executed 409 if that key already finished, with its outcome; outcome_unknown 409 if it is in flight or unresolved) -> every ancestor run's own grant and limits (action_not_in_run 403 outside an ancestor grant; run_limit_reached 429 once the run or an ancestor used up its calls) -> the agent loop breaker, which refuses a call repeating the same method+path+query+body hash too many times in its window, or at a too-steady machine cadence (loop_detected, 429, `x-odile-gate-loop-detected: true` and `retry-after`, unless observing) -> the app's per-minute limit (rate_limited, 429, `retry-after`) -> the project's monthly plan quota, unless a prepaid x402 call pack covers it or the plan is Gate's own internal plan (monthly_quota, 429; the message names the extra-call limit on Pro, and mentions buying a pack when X402_PACKS or X402_BEARER_PACKS is enabled) -> decrypting the upstream secret header, if configured (secret_unavailable, 503) -> re-checks of policy/run/approval-expiry/handoff/AWS state taken right before the send, since nothing may await between them and the fetch (policy_changed 409; run_revoked/run_expired 403; approval_expired 403; key_expired/call_limit_reached; aws_subscription_inactive 402) -> request signing, only when the SIGNED_REQUESTS env flag is on (currently \"0\", so these are unreachable today) and this app has signing enabled: signing_key_missing 503 with no active key, signing_key_unavailable 503 if the key cannot be decrypted, signing_failed 502 if signing itself throws (the call is never sent unsigned) -> the upstream fetch, under the project's own timeout (upstream_timeout, 502) or on any fetch error (upstream_error, 502) -> optional response filtering (an admin-set JSON-Pointer allow-list): a non-JSON or malformed upstream body, or one over 1 MB or slower than the redaction timeout, is withheld (response_redaction_failed, 502; a write may already have executed, so the body says not to retry with a new key) -- a policy change caught exactly here reuses the same response_redaction_failed reason even though nothing was actually withheld for redaction, because the upstream call has already been made and cannot be unmade.\n\nA key_expired, call_limit_reached, loop_detected, run_limit_reached or outcome_unknown refusal also carries a `recovery` object (`retry_after_seconds`, `do`: stop/wait_then_retry_once/call_recover/ask_human, `hint`) telling the caller what to do next; `call_recover` is only used for an outcome_unknown write this exact call could recover with POST .../_gate/recover.\n\nA hold for approval answers 202 with action_id, expires_at, a `resume` hint, and (only when the project has a risk model configured) a `risk` score and its top contributing `risk_features`. A plain call that clears every check forwards the upstream's exact status, body and most headers; if response filtering is on, the body is replaced by the selected JSON subtree and the headers are replaced by just content-type, cache-control, x-gate-redacted: allow-list and any CORS headers the upstream sent. Either way Gate appends a `server-timing` header (gate;dur=..., upstream;dur=..., and redaction;dur=... when filtering ran).\n\nRecovery (POST only; always needs x-odile-run and an idempotency-key header naming the write to recover): POST .../_gate/recover asks the run action's configured check (a GET the run itself could make) whether a write with that Idempotency-Key happened, and settles it. Refusals specific to this call: method_not_allowed (405, non-POST), bad_run (401, missing or unknown x-odile-run), idempotency_key_required (400, missing/over 255 chars), no_such_operation (404, no write with that key in this run), still_running (409, the write is still in flight), no_check (409, the run action was granted with no check), check_not_allowed (403, the check path is template-refused or is not itself a read this run/app/user could make), bad_user_token (401, the check reads a per-user route and x-odile-user-token is missing or invalid), rate_limited (429, the check spends the app's per-minute limit like any call), secret_unavailable (503), recover_conflict (409, the write's state changed while Gate was checking), and the same policy_changed/run_revoked/run_expired/aws_subscription_inactive re-checks as above. On success (200, `x-odile-outcome` header, never logged as a refusal): a 404 from the check settles the write as executed (outcome: executed, recovered: true, with a short evidence object when the check returned one); a 404 settles it as safe to retry once, but only when the action was granted with idempotent: true (outcome: not_executed, safe_to_retry: true) -- otherwise it is outcome: needs_review with found: false, since a late-landing write could then run twice; a check with no clear answer (not a 404, and not a JSON list, {data:[...]}, or one object with an id) is also needs_review. A write already marked done answers outcome: executed immediately without calling the check again.\n\nBodies: a write's body is read up to 10 MB (413 past that; 1 MB while an approval is pending and uncommitted); it is forwarded as the exact bytes received (any content type, not just JSON) and is never stored, only hashed, except the 1 MB sealed copy of a body held for approval, whose path, query and body are cleared after a known execution outcome, rejection or expiry cleanup; unknown outcomes retain that content pending resolution or expiry cleanup.","security":[{"appKey":[]},{"appKey":[],"runToken":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"path","in":"path","required":true,"schema":{"type":"string"},"description":"The upstream call, rest-of-path and query string, exactly as it is appended to the project's configured upstream base URL (e.g. 'orders/42?expand=items'), except for the literal values _gate/run, _gate/run/delegate, _gate/actions/{id} and _gate/recover, which Gate handles itself. May contain further slashes; must not contain an encoded slash/backslash, a dot segment, or a control character (refused as unsafe_path)."},{"name":"x-odile-run","in":"header","required":false,"schema":{"type":"string"},"description":"A Gate Actions run token (gr_...). Required when the app's run mode is `all`, or `writes` and this is a write; always required on POST .../_gate/recover."},{"name":"x-odile-action","in":"header","required":false,"schema":{"type":"string"},"description":"The action_id from a prior 202 approval_required response, to resume that exact held call once a person has approved it."},{"name":"x-odile-user-token","in":"header","required":false,"schema":{"type":"string"},"description":"A signed-in end user's JWT (RS256/ES256/EdDSA), required only for a route whose allow-list rule names {user} or a ?key={user} pin, when the project has user_tokens configured."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Required on a write made inside a run (idempotency_key_required if missing), and on POST .../_gate/recover to name the write being recovered. A repeat of the same key on the same run is never resent."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"The upstream's own response, status and body unchanged (or, if the app has response filtering configured, the allow-listed JSON subtree only). Headers are the upstream's own minus hop-by-hop and set-cookie (or, when filtered, just content-type, cache-control, x-gate-redacted and any CORS headers), plus Gate's server-timing header.","headers":{"server-timing":{"schema":{"type":"string"},"description":"gate;dur=<ms>, upstream;dur=<ms>[, redaction;dur=<ms>]"},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"*/*":{"schema":{}}}},"202":{"description":"The call needs approval and has been held; it did not reach the upstream. A person must approve it in the dashboard, then the agent resends the identical call with x-odile-action. Follow Location or status_url with GET using the same app key and the same run token when the held call used one. job_id equals action_id. This is a human approval hold, not automatic background execution. Only x-odile-outcome: approval_required identifies a Gate hold; an upstream API may return an unrelated 202 with its own body and headers.","headers":{"x-odile-outcome":{"schema":{"type":"string","const":"approval_required"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"Location":{"$ref":"#/components/headers/ActionLocation"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/GwApprovalHeld"},{"description":"Unmodified upstream 202 body. Gate does not know its schema, job identity or polling contract."}]}},"*/*":{"schema":{"description":"An upstream 202 may use any media type, or have an empty body. Follow that API's contract."}}},"links":{"actionStatus":{"operationId":"agentGetAction","parameters":{"project_id":"$request.path.project_id","action_id":"$response.body#/action_id"},"description":"Poll the held action using the same app key and run token; wait for human approval before replay."}}},"400":{"description":"Refused. required_field_missing also returns `missing`, an array of the field names the held call's JSON body must carry. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","headers":{"x-gate-refused":{"description":"One of: unsafe_path, required_field_missing, idempotency_key_required. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}}},"401":{"description":"Refused. key_expired also includes a `recovery` hint object (`retry_after_seconds`, `do`, `hint`).","headers":{"x-gate-refused":{"description":"One of: bad_key, key_expired, bad_run, bad_user_token. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Refused. This project's AWS Marketplace subscription is inactive. Body is exactly {error: 'aws_subscription_inactive', message}; no x-gate-refused header, and the call is not written to the audit log.","headers":{"x-gate-refused":{"description":"One of: aws_subscription_inactive. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused. action_not_in_run also returns `allowed`, the run's own granted rules, as an array of \"METHOD /path\" strings. model_not_allowed also returns `allowed`, the app's model allow-list.","headers":{"x-gate-refused":{"description":"One of: app_suspended, ip_not_allowed, run_revoked, run_expired, action_not_in_run, run_required, user_tokens_off, outside_user_scope, route_not_allowed, blocked_by_rule, model_not_allowed, bad_action, approval_rejected, approval_expired, check_not_allowed. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Refused. project_not_found carries exactly {error: 'project not found'}, with no x-gate-refused header, before any auth check.","headers":{"x-gate-refused":{"description":"One of: project_not_found, no_such_operation. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Refused. POST .../_gate/recover only; any other method on that path is refused here.","headers":{"x-gate-refused":{"description":"One of: method_not_allowed. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refused. already_executed also returns `outcome_status` (and, on the idempotency-key path, `at`). approval_pending/approval_rejected/approval_expired/bad_action/already_executed also return `action_id`. outcome_unknown also includes a `recovery` hint object (`retry_after_seconds`, `do`, `hint`; `do: call_recover` only when this exact call is itself recoverable).","headers":{"x-gate-refused":{"description":"One of: policy_changed, approval_pending, already_executed, outcome_unknown, approval_mismatch, still_running, no_check, recover_conflict. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Refused. body_too_large is the 10 MB request cap; approval_body_too_large is the 1 MB cap on a body held for approval, before it is resumed with x-odile-action.","headers":{"x-gate-refused":{"description":"One of: body_too_large, approval_body_too_large. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Refused. rate_limited and loop_detected also return `retry_after_seconds` and a matching `retry-after` header; loop_detected also sets `x-odile-gate-loop-detected: true`. call_limit_reached, loop_detected and run_limit_reached also include a `recovery` hint object (`retry_after_seconds`, `do`, `hint`).","headers":{"x-gate-refused":{"description":"One of: call_limit_reached, run_limit_reached, rate_limited, loop_detected, monthly_quota. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}},"Retry-After":{"description":"Delay in seconds for time-based limits (minute, loop or monthly quota), or the upstream Retry-After value. Lifetime app/run allowances do not refill on a timer and omit this header; follow the refusal recovery instructions.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Refused. response_redaction_failed also returns `upstream_status` and a `recovery` object saying the write may already have executed and must not be retried with a new Idempotency-Key.","headers":{"x-gate-refused":{"description":"One of: signing_failed, upstream_timeout, upstream_error, response_redaction_failed. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Refused. signing_key_missing/signing_key_unavailable/signing_failed (502 above) only occur when the SIGNED_REQUESTS env flag is on; it is currently \"0\" (off) per wrangler.toml, so these three are not reachable today.","headers":{"x-gate-refused":{"description":"One of: secret_unavailable, approval_unavailable, signing_key_missing, signing_key_unavailable. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Gateway"],"operationId":"gwProxyPost","summary":"Proxy a POST call through Gate (also handles POST .../_gate/recover).","description":"Forwards one call to the project's own upstream API through its allow-list, exactly as the app key's rules permit. This is the one route every Gate app actually calls; everything else in the API manages the project. The {path} segment (which may contain further slashes and a query string) is appended to the project's configured upstream base URL unchanged, except for `/_gate/run`, `/_gate/run/delegate`, `/_gate/actions/{id}` and `/_gate/recover`, which Gate intercepts itself and never forwards (out of scope here; see the Gate Actions/recovery fragment, except for the outcome_unknown recovery flow below, which this fragment documents because it is reached through this same proxy path).\n\nAuth: `Authorization: Bearer <app key>` (gw_... is wrong; app keys match APP_KEY) is required on every call. `x-odile-run` (a Gate Actions run token) is additionally required when the app's run mode is `all`, or `writes` and the method is a write (anything but GET/HEAD/OPTIONS), and is always required on `POST .../_gate/recover`. When a run token is sent, the call must match one of the run's granted actions (and every ancestor run's, for a delegated run) or it is refused with action_not_in_run.\n\nRequest headers Gate reads: `authorization` (the app key), `x-odile-run` (run token), `x-odile-action` (resumes a call that was held for approval, with the action id returned by the 202), `x-odile-user-token` (a signed-in user's JWT, for a route with a {user} or ?key={user} placeholder; needs user_tokens configured on the project or a 403), and `idempotency-key` (required on a write made inside a run, and on `POST .../_gate/recover`, up to 255 characters; a repeat of the same key on the same run gets already_executed or outcome_unknown instead of being resent). Gate also reads `content-length` to pre-check the 10 MB body cap. `x-gate-ip` and `x-gate-country` are set internally by the public worker from the real connecting IP/CF country and are not something a caller sets; any `x-gate-*` header a caller sends is deleted before this Durable Object ever sees it.\n\nHeaders dropped before the call reaches the upstream: hop-by-hop headers (connection, keep-alive, proxy-connection, proxy-authenticate, proxy-authorization, te, trailer, transfer-encoding, upgrade) and anything the client listed in its own Connection header, plus authorization, cookie, host, content-length, expect, forwarded, x-real-ip, true-client-ip, x-http-method-override/x-http-method/x-method-override, x-original-url/x-rewrite-url/x-original-uri/x-original-method, x-odile-user-token, x-odile-run, x-odile-action, and every cf-*, x-forwarded-* and x-gate-* header. The project's own upstream secret header (if configured) is injected here instead. Response headers dropped on the way back: the same hop-by-hop set plus set-cookie (one Gate host serves every project, so an upstream's cookie must never reach another project's caller).\n\nChecks run in this order, each able to refuse the call (reason is the `x-gate-refused` header and the JSON `error` field, both from the GwRefusal values below, unless noted): the project exists (project_not_found, 404, no refusal header, not logged) and is not an inactive AWS Marketplace subscription (aws_subscription_inactive, 402, no `x-gate-refused` header and no audit row at all -- checked again right before the upstream send) -> the app key (bad_key, 401; only the first 20 bad-key calls an hour get an audit row) -> a Pro client-handoff key's expiry/call cap (key_expired 401 / call_limit_reached 429) -> the app is not suspended (app_suspended, 403) -> the caller's IP against the project's allow-list (ip_not_allowed, 403, unless the project is in observe mode, which logs and forwards instead) -> the path has no encoded slash/backslash/dot-segment/control character (unsafe_path, 400) -> the app's own route allow-list and template (route_not_allowed, 403, for a template-refused route or no matching allow-list rule) -> a per-user route's x-odile-user-token (user_tokens_off 403 if the project has none configured; bad_user_token 401 if missing/invalid/expired; outside_user_scope 403 if it names a different user) -> the 10 MB body cap (body_too_large, 413) -> a _method field in the query or in a form, multipart or JSON body (method_override, 403, even when observing: Rails, Laravel and Symfony APIs would run that method instead of the one Gate checked) -> the project's regex block rules over the path, query and whole decoded body (blocked_by_rule, 403, unless observing) -> an app-level model allow-list, read out of the body/query/content-type (model_not_allowed, 403, also on an unreadable body, unless observing) -> the x-odile-run token, if the app's run mode requires one (run_required, 403) or one was sent (bad_run 401 if unknown/other app; run_revoked/run_expired 403 if the run or an ancestor is no longer active; action_not_in_run 403 if this method+path is not one of the run's granted actions, listing the ones that are) -> approval requirements, templated or set on the run action: with no x-odile-action header, the call is held (see 202 below) once its body fits the 1 MB approval cap (approval_body_too_large, 413, otherwise) and carries every field the template requires (required_field_missing, 400); with one, the action must exist (bad_action 403), be approved (approval_pending 409 / approval_rejected 403 / approval_expired 403 / already_executed 409 with its outcome / outcome_unknown 409 if it is mid-flight or unresolved), and match this exact call's method, path+query and forwarded headers and body hash (approval_mismatch, 409) -> a run write's Idempotency-Key (idempotency_key_required 400; already_executed 409 if that key already finished, with its outcome; outcome_unknown 409 if it is in flight or unresolved) -> every ancestor run's own grant and limits (action_not_in_run 403 outside an ancestor grant; run_limit_reached 429 once the run or an ancestor used up its calls) -> the agent loop breaker, which refuses a call repeating the same method+path+query+body hash too many times in its window, or at a too-steady machine cadence (loop_detected, 429, `x-odile-gate-loop-detected: true` and `retry-after`, unless observing) -> the app's per-minute limit (rate_limited, 429, `retry-after`) -> the project's monthly plan quota, unless a prepaid x402 call pack covers it or the plan is Gate's own internal plan (monthly_quota, 429; the message names the extra-call limit on Pro, and mentions buying a pack when X402_PACKS or X402_BEARER_PACKS is enabled) -> decrypting the upstream secret header, if configured (secret_unavailable, 503) -> re-checks of policy/run/approval-expiry/handoff/AWS state taken right before the send, since nothing may await between them and the fetch (policy_changed 409; run_revoked/run_expired 403; approval_expired 403; key_expired/call_limit_reached; aws_subscription_inactive 402) -> request signing, only when the SIGNED_REQUESTS env flag is on (currently \"0\", so these are unreachable today) and this app has signing enabled: signing_key_missing 503 with no active key, signing_key_unavailable 503 if the key cannot be decrypted, signing_failed 502 if signing itself throws (the call is never sent unsigned) -> the upstream fetch, under the project's own timeout (upstream_timeout, 502) or on any fetch error (upstream_error, 502) -> optional response filtering (an admin-set JSON-Pointer allow-list): a non-JSON or malformed upstream body, or one over 1 MB or slower than the redaction timeout, is withheld (response_redaction_failed, 502; a write may already have executed, so the body says not to retry with a new key) -- a policy change caught exactly here reuses the same response_redaction_failed reason even though nothing was actually withheld for redaction, because the upstream call has already been made and cannot be unmade.\n\nA key_expired, call_limit_reached, loop_detected, run_limit_reached or outcome_unknown refusal also carries a `recovery` object (`retry_after_seconds`, `do`: stop/wait_then_retry_once/call_recover/ask_human, `hint`) telling the caller what to do next; `call_recover` is only used for an outcome_unknown write this exact call could recover with POST .../_gate/recover.\n\nA hold for approval answers 202 with action_id, expires_at, a `resume` hint, and (only when the project has a risk model configured) a `risk` score and its top contributing `risk_features`. A plain call that clears every check forwards the upstream's exact status, body and most headers; if response filtering is on, the body is replaced by the selected JSON subtree and the headers are replaced by just content-type, cache-control, x-gate-redacted: allow-list and any CORS headers the upstream sent. Either way Gate appends a `server-timing` header (gate;dur=..., upstream;dur=..., and redaction;dur=... when filtering ran).\n\nRecovery (POST only; always needs x-odile-run and an idempotency-key header naming the write to recover): POST .../_gate/recover asks the run action's configured check (a GET the run itself could make) whether a write with that Idempotency-Key happened, and settles it. Refusals specific to this call: method_not_allowed (405, non-POST), bad_run (401, missing or unknown x-odile-run), idempotency_key_required (400, missing/over 255 chars), no_such_operation (404, no write with that key in this run), still_running (409, the write is still in flight), no_check (409, the run action was granted with no check), check_not_allowed (403, the check path is template-refused or is not itself a read this run/app/user could make), bad_user_token (401, the check reads a per-user route and x-odile-user-token is missing or invalid), rate_limited (429, the check spends the app's per-minute limit like any call), secret_unavailable (503), recover_conflict (409, the write's state changed while Gate was checking), and the same policy_changed/run_revoked/run_expired/aws_subscription_inactive re-checks as above. On success (200, `x-odile-outcome` header, never logged as a refusal): a 404 from the check settles the write as executed (outcome: executed, recovered: true, with a short evidence object when the check returned one); a 404 settles it as safe to retry once, but only when the action was granted with idempotent: true (outcome: not_executed, safe_to_retry: true) -- otherwise it is outcome: needs_review with found: false, since a late-landing write could then run twice; a check with no clear answer (not a 404, and not a JSON list, {data:[...]}, or one object with an id) is also needs_review. A write already marked done answers outcome: executed immediately without calling the check again.\n\nBodies: a write's body is read up to 10 MB (413 past that; 1 MB while an approval is pending and uncommitted); it is forwarded as the exact bytes received (any content type, not just JSON) and is never stored, only hashed, except the 1 MB sealed copy of a body held for approval, whose path, query and body are cleared after a known execution outcome, rejection or expiry cleanup; unknown outcomes retain that content pending resolution or expiry cleanup.","security":[{"appKey":[]},{"appKey":[],"runToken":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"path","in":"path","required":true,"schema":{"type":"string"},"description":"The upstream call, rest-of-path and query string, exactly as it is appended to the project's configured upstream base URL (e.g. 'orders/42?expand=items'), except for the literal values _gate/run, _gate/run/delegate, _gate/actions/{id} and _gate/recover, which Gate handles itself. May contain further slashes; must not contain an encoded slash/backslash, a dot segment, or a control character (refused as unsafe_path)."},{"name":"x-odile-run","in":"header","required":false,"schema":{"type":"string"},"description":"A Gate Actions run token (gr_...). Required when the app's run mode is `all`, or `writes` and this is a write; always required on POST .../_gate/recover."},{"name":"x-odile-action","in":"header","required":false,"schema":{"type":"string"},"description":"The action_id from a prior 202 approval_required response, to resume that exact held call once a person has approved it."},{"name":"x-odile-user-token","in":"header","required":false,"schema":{"type":"string"},"description":"A signed-in end user's JWT (RS256/ES256/EdDSA), required only for a route whose allow-list rule names {user} or a ?key={user} pin, when the project has user_tokens configured."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Required on a write made inside a run (idempotency_key_required if missing), and on POST .../_gate/recover to name the write being recovered. A repeat of the same key on the same run is never resent."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"The upstream's own response, status and body unchanged (or, if the app has response filtering configured, the allow-listed JSON subtree only). Headers are the upstream's own minus hop-by-hop and set-cookie (or, when filtered, just content-type, cache-control, x-gate-redacted and any CORS headers), plus Gate's server-timing header.","headers":{"server-timing":{"schema":{"type":"string"},"description":"gate;dur=<ms>, upstream;dur=<ms>[, redaction;dur=<ms>]"},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"*/*":{"schema":{}}}},"202":{"description":"The call needs approval and has been held; it did not reach the upstream. A person must approve it in the dashboard, then the agent resends the identical call with x-odile-action. Follow Location or status_url with GET using the same app key and the same run token when the held call used one. job_id equals action_id. This is a human approval hold, not automatic background execution. Only x-odile-outcome: approval_required identifies a Gate hold; an upstream API may return an unrelated 202 with its own body and headers.","headers":{"x-odile-outcome":{"schema":{"type":"string","const":"approval_required"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"Location":{"$ref":"#/components/headers/ActionLocation"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/GwApprovalHeld"},{"description":"Unmodified upstream 202 body. Gate does not know its schema, job identity or polling contract."}]}},"*/*":{"schema":{"description":"An upstream 202 may use any media type, or have an empty body. Follow that API's contract."}}},"links":{"actionStatus":{"operationId":"agentGetAction","parameters":{"project_id":"$request.path.project_id","action_id":"$response.body#/action_id"},"description":"Poll the held action using the same app key and run token; wait for human approval before replay."}}},"400":{"description":"Refused. required_field_missing also returns `missing`, an array of the field names the held call's JSON body must carry. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","headers":{"x-gate-refused":{"description":"One of: unsafe_path, required_field_missing, idempotency_key_required. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}}},"401":{"description":"Refused. key_expired also includes a `recovery` hint object (`retry_after_seconds`, `do`, `hint`).","headers":{"x-gate-refused":{"description":"One of: bad_key, key_expired, bad_run, bad_user_token. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Refused. This project's AWS Marketplace subscription is inactive. Body is exactly {error: 'aws_subscription_inactive', message}; no x-gate-refused header, and the call is not written to the audit log.","headers":{"x-gate-refused":{"description":"One of: aws_subscription_inactive. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused. action_not_in_run also returns `allowed`, the run's own granted rules, as an array of \"METHOD /path\" strings. model_not_allowed also returns `allowed`, the app's model allow-list.","headers":{"x-gate-refused":{"description":"One of: app_suspended, ip_not_allowed, run_revoked, run_expired, action_not_in_run, run_required, user_tokens_off, outside_user_scope, route_not_allowed, blocked_by_rule, model_not_allowed, bad_action, approval_rejected, approval_expired, check_not_allowed. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Refused. project_not_found carries exactly {error: 'project not found'}, with no x-gate-refused header, before any auth check.","headers":{"x-gate-refused":{"description":"One of: project_not_found, no_such_operation. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Refused. POST .../_gate/recover only; any other method on that path is refused here.","headers":{"x-gate-refused":{"description":"One of: method_not_allowed. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refused. already_executed also returns `outcome_status` (and, on the idempotency-key path, `at`). approval_pending/approval_rejected/approval_expired/bad_action/already_executed also return `action_id`. outcome_unknown also includes a `recovery` hint object (`retry_after_seconds`, `do`, `hint`; `do: call_recover` only when this exact call is itself recoverable).","headers":{"x-gate-refused":{"description":"One of: policy_changed, approval_pending, already_executed, outcome_unknown, approval_mismatch, still_running, no_check, recover_conflict. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Refused. body_too_large is the 10 MB request cap; approval_body_too_large is the 1 MB cap on a body held for approval, before it is resumed with x-odile-action.","headers":{"x-gate-refused":{"description":"One of: body_too_large, approval_body_too_large. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Refused. rate_limited and loop_detected also return `retry_after_seconds` and a matching `retry-after` header; loop_detected also sets `x-odile-gate-loop-detected: true`. call_limit_reached, loop_detected and run_limit_reached also include a `recovery` hint object (`retry_after_seconds`, `do`, `hint`).","headers":{"x-gate-refused":{"description":"One of: call_limit_reached, run_limit_reached, rate_limited, loop_detected, monthly_quota. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}},"Retry-After":{"description":"Delay in seconds for time-based limits (minute, loop or monthly quota), or the upstream Retry-After value. Lifetime app/run allowances do not refill on a timer and omit this header; follow the refusal recovery instructions.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Refused. response_redaction_failed also returns `upstream_status` and a `recovery` object saying the write may already have executed and must not be retried with a new Idempotency-Key.","headers":{"x-gate-refused":{"description":"One of: signing_failed, upstream_timeout, upstream_error, response_redaction_failed. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Refused. signing_key_missing/signing_key_unavailable/signing_failed (502 above) only occur when the SIGNED_REQUESTS env flag is on; it is currently \"0\" (off) per wrangler.toml, so these three are not reachable today.","headers":{"x-gate-refused":{"description":"One of: secret_unavailable, approval_unavailable, signing_key_missing, signing_key_unavailable. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"description":"Forwarded to the upstream exactly as received, any content type, up to 10 MB (1 MB while the call is held for approval and has not yet been resumed with x-odile-action). Ordinary request bodies are not stored, only hashed. Approval holds retain the path, query and body encrypted until a known execution outcome, rejection or expiry cleanup; unknown outcomes retain them pending resolution or expiry cleanup. Gate can inspect request bodies for configured block rules, model limits and required approval fields.","content":{"*/*":{"schema":{"type":"string","format":"binary"}}}}},"put":{"tags":["Gateway"],"operationId":"gwProxyPut","summary":"Proxy a PUT call through Gate to the project's upstream API.","description":"Forwards one call to the project's own upstream API through its allow-list, exactly as the app key's rules permit. This is the one route every Gate app actually calls; everything else in the API manages the project. The {path} segment (which may contain further slashes and a query string) is appended to the project's configured upstream base URL unchanged, except for `/_gate/run`, `/_gate/run/delegate`, `/_gate/actions/{id}` and `/_gate/recover`, which Gate intercepts itself and never forwards (out of scope here; see the Gate Actions/recovery fragment, except for the outcome_unknown recovery flow below, which this fragment documents because it is reached through this same proxy path).\n\nAuth: `Authorization: Bearer <app key>` (gw_... is wrong; app keys match APP_KEY) is required on every call. `x-odile-run` (a Gate Actions run token) is additionally required when the app's run mode is `all`, or `writes` and the method is a write (anything but GET/HEAD/OPTIONS), and is always required on `POST .../_gate/recover`. When a run token is sent, the call must match one of the run's granted actions (and every ancestor run's, for a delegated run) or it is refused with action_not_in_run.\n\nRequest headers Gate reads: `authorization` (the app key), `x-odile-run` (run token), `x-odile-action` (resumes a call that was held for approval, with the action id returned by the 202), `x-odile-user-token` (a signed-in user's JWT, for a route with a {user} or ?key={user} placeholder; needs user_tokens configured on the project or a 403), and `idempotency-key` (required on a write made inside a run, and on `POST .../_gate/recover`, up to 255 characters; a repeat of the same key on the same run gets already_executed or outcome_unknown instead of being resent). Gate also reads `content-length` to pre-check the 10 MB body cap. `x-gate-ip` and `x-gate-country` are set internally by the public worker from the real connecting IP/CF country and are not something a caller sets; any `x-gate-*` header a caller sends is deleted before this Durable Object ever sees it.\n\nHeaders dropped before the call reaches the upstream: hop-by-hop headers (connection, keep-alive, proxy-connection, proxy-authenticate, proxy-authorization, te, trailer, transfer-encoding, upgrade) and anything the client listed in its own Connection header, plus authorization, cookie, host, content-length, expect, forwarded, x-real-ip, true-client-ip, x-http-method-override/x-http-method/x-method-override, x-original-url/x-rewrite-url/x-original-uri/x-original-method, x-odile-user-token, x-odile-run, x-odile-action, and every cf-*, x-forwarded-* and x-gate-* header. The project's own upstream secret header (if configured) is injected here instead. Response headers dropped on the way back: the same hop-by-hop set plus set-cookie (one Gate host serves every project, so an upstream's cookie must never reach another project's caller).\n\nChecks run in this order, each able to refuse the call (reason is the `x-gate-refused` header and the JSON `error` field, both from the GwRefusal values below, unless noted): the project exists (project_not_found, 404, no refusal header, not logged) and is not an inactive AWS Marketplace subscription (aws_subscription_inactive, 402, no `x-gate-refused` header and no audit row at all -- checked again right before the upstream send) -> the app key (bad_key, 401; only the first 20 bad-key calls an hour get an audit row) -> a Pro client-handoff key's expiry/call cap (key_expired 401 / call_limit_reached 429) -> the app is not suspended (app_suspended, 403) -> the caller's IP against the project's allow-list (ip_not_allowed, 403, unless the project is in observe mode, which logs and forwards instead) -> the path has no encoded slash/backslash/dot-segment/control character (unsafe_path, 400) -> the app's own route allow-list and template (route_not_allowed, 403, for a template-refused route or no matching allow-list rule) -> a per-user route's x-odile-user-token (user_tokens_off 403 if the project has none configured; bad_user_token 401 if missing/invalid/expired; outside_user_scope 403 if it names a different user) -> the 10 MB body cap (body_too_large, 413) -> a _method field in the query or in a form, multipart or JSON body (method_override, 403, even when observing: Rails, Laravel and Symfony APIs would run that method instead of the one Gate checked) -> the project's regex block rules over the path, query and whole decoded body (blocked_by_rule, 403, unless observing) -> an app-level model allow-list, read out of the body/query/content-type (model_not_allowed, 403, also on an unreadable body, unless observing) -> the x-odile-run token, if the app's run mode requires one (run_required, 403) or one was sent (bad_run 401 if unknown/other app; run_revoked/run_expired 403 if the run or an ancestor is no longer active; action_not_in_run 403 if this method+path is not one of the run's granted actions, listing the ones that are) -> approval requirements, templated or set on the run action: with no x-odile-action header, the call is held (see 202 below) once its body fits the 1 MB approval cap (approval_body_too_large, 413, otherwise) and carries every field the template requires (required_field_missing, 400); with one, the action must exist (bad_action 403), be approved (approval_pending 409 / approval_rejected 403 / approval_expired 403 / already_executed 409 with its outcome / outcome_unknown 409 if it is mid-flight or unresolved), and match this exact call's method, path+query and forwarded headers and body hash (approval_mismatch, 409) -> a run write's Idempotency-Key (idempotency_key_required 400; already_executed 409 if that key already finished, with its outcome; outcome_unknown 409 if it is in flight or unresolved) -> every ancestor run's own grant and limits (action_not_in_run 403 outside an ancestor grant; run_limit_reached 429 once the run or an ancestor used up its calls) -> the agent loop breaker, which refuses a call repeating the same method+path+query+body hash too many times in its window, or at a too-steady machine cadence (loop_detected, 429, `x-odile-gate-loop-detected: true` and `retry-after`, unless observing) -> the app's per-minute limit (rate_limited, 429, `retry-after`) -> the project's monthly plan quota, unless a prepaid x402 call pack covers it or the plan is Gate's own internal plan (monthly_quota, 429; the message names the extra-call limit on Pro, and mentions buying a pack when X402_PACKS or X402_BEARER_PACKS is enabled) -> decrypting the upstream secret header, if configured (secret_unavailable, 503) -> re-checks of policy/run/approval-expiry/handoff/AWS state taken right before the send, since nothing may await between them and the fetch (policy_changed 409; run_revoked/run_expired 403; approval_expired 403; key_expired/call_limit_reached; aws_subscription_inactive 402) -> request signing, only when the SIGNED_REQUESTS env flag is on (currently \"0\", so these are unreachable today) and this app has signing enabled: signing_key_missing 503 with no active key, signing_key_unavailable 503 if the key cannot be decrypted, signing_failed 502 if signing itself throws (the call is never sent unsigned) -> the upstream fetch, under the project's own timeout (upstream_timeout, 502) or on any fetch error (upstream_error, 502) -> optional response filtering (an admin-set JSON-Pointer allow-list): a non-JSON or malformed upstream body, or one over 1 MB or slower than the redaction timeout, is withheld (response_redaction_failed, 502; a write may already have executed, so the body says not to retry with a new key) -- a policy change caught exactly here reuses the same response_redaction_failed reason even though nothing was actually withheld for redaction, because the upstream call has already been made and cannot be unmade.\n\nA key_expired, call_limit_reached, loop_detected, run_limit_reached or outcome_unknown refusal also carries a `recovery` object (`retry_after_seconds`, `do`: stop/wait_then_retry_once/call_recover/ask_human, `hint`) telling the caller what to do next; `call_recover` is only used for an outcome_unknown write this exact call could recover with POST .../_gate/recover.\n\nA hold for approval answers 202 with action_id, expires_at, a `resume` hint, and (only when the project has a risk model configured) a `risk` score and its top contributing `risk_features`. A plain call that clears every check forwards the upstream's exact status, body and most headers; if response filtering is on, the body is replaced by the selected JSON subtree and the headers are replaced by just content-type, cache-control, x-gate-redacted: allow-list and any CORS headers the upstream sent. Either way Gate appends a `server-timing` header (gate;dur=..., upstream;dur=..., and redaction;dur=... when filtering ran).\n\nRecovery (POST only; always needs x-odile-run and an idempotency-key header naming the write to recover): POST .../_gate/recover asks the run action's configured check (a GET the run itself could make) whether a write with that Idempotency-Key happened, and settles it. Refusals specific to this call: method_not_allowed (405, non-POST), bad_run (401, missing or unknown x-odile-run), idempotency_key_required (400, missing/over 255 chars), no_such_operation (404, no write with that key in this run), still_running (409, the write is still in flight), no_check (409, the run action was granted with no check), check_not_allowed (403, the check path is template-refused or is not itself a read this run/app/user could make), bad_user_token (401, the check reads a per-user route and x-odile-user-token is missing or invalid), rate_limited (429, the check spends the app's per-minute limit like any call), secret_unavailable (503), recover_conflict (409, the write's state changed while Gate was checking), and the same policy_changed/run_revoked/run_expired/aws_subscription_inactive re-checks as above. On success (200, `x-odile-outcome` header, never logged as a refusal): a 404 from the check settles the write as executed (outcome: executed, recovered: true, with a short evidence object when the check returned one); a 404 settles it as safe to retry once, but only when the action was granted with idempotent: true (outcome: not_executed, safe_to_retry: true) -- otherwise it is outcome: needs_review with found: false, since a late-landing write could then run twice; a check with no clear answer (not a 404, and not a JSON list, {data:[...]}, or one object with an id) is also needs_review. A write already marked done answers outcome: executed immediately without calling the check again.\n\nBodies: a write's body is read up to 10 MB (413 past that; 1 MB while an approval is pending and uncommitted); it is forwarded as the exact bytes received (any content type, not just JSON) and is never stored, only hashed, except the 1 MB sealed copy of a body held for approval, whose path, query and body are cleared after a known execution outcome, rejection or expiry cleanup; unknown outcomes retain that content pending resolution or expiry cleanup.","security":[{"appKey":[]},{"appKey":[],"runToken":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"path","in":"path","required":true,"schema":{"type":"string"},"description":"The upstream call, rest-of-path and query string, exactly as it is appended to the project's configured upstream base URL (e.g. 'orders/42?expand=items'), except for the literal values _gate/run, _gate/run/delegate, _gate/actions/{id} and _gate/recover, which Gate handles itself. May contain further slashes; must not contain an encoded slash/backslash, a dot segment, or a control character (refused as unsafe_path)."},{"name":"x-odile-run","in":"header","required":false,"schema":{"type":"string"},"description":"A Gate Actions run token (gr_...). Required when the app's run mode is `all`, or `writes` and this is a write; always required on POST .../_gate/recover."},{"name":"x-odile-action","in":"header","required":false,"schema":{"type":"string"},"description":"The action_id from a prior 202 approval_required response, to resume that exact held call once a person has approved it."},{"name":"x-odile-user-token","in":"header","required":false,"schema":{"type":"string"},"description":"A signed-in end user's JWT (RS256/ES256/EdDSA), required only for a route whose allow-list rule names {user} or a ?key={user} pin, when the project has user_tokens configured."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Required on a write made inside a run (idempotency_key_required if missing), and on POST .../_gate/recover to name the write being recovered. A repeat of the same key on the same run is never resent."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"The upstream's own response, status and body unchanged (or, if the app has response filtering configured, the allow-listed JSON subtree only). Headers are the upstream's own minus hop-by-hop and set-cookie (or, when filtered, just content-type, cache-control, x-gate-redacted and any CORS headers), plus Gate's server-timing header.","headers":{"server-timing":{"schema":{"type":"string"},"description":"gate;dur=<ms>, upstream;dur=<ms>[, redaction;dur=<ms>]"},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"*/*":{"schema":{}}}},"202":{"description":"The call needs approval and has been held; it did not reach the upstream. A person must approve it in the dashboard, then the agent resends the identical call with x-odile-action. Follow Location or status_url with GET using the same app key and the same run token when the held call used one. job_id equals action_id. This is a human approval hold, not automatic background execution. Only x-odile-outcome: approval_required identifies a Gate hold; an upstream API may return an unrelated 202 with its own body and headers.","headers":{"x-odile-outcome":{"schema":{"type":"string","const":"approval_required"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"Location":{"$ref":"#/components/headers/ActionLocation"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/GwApprovalHeld"},{"description":"Unmodified upstream 202 body. Gate does not know its schema, job identity or polling contract."}]}},"*/*":{"schema":{"description":"An upstream 202 may use any media type, or have an empty body. Follow that API's contract."}}},"links":{"actionStatus":{"operationId":"agentGetAction","parameters":{"project_id":"$request.path.project_id","action_id":"$response.body#/action_id"},"description":"Poll the held action using the same app key and run token; wait for human approval before replay."}}},"400":{"description":"Refused. required_field_missing also returns `missing`, an array of the field names the held call's JSON body must carry. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","headers":{"x-gate-refused":{"description":"One of: unsafe_path, required_field_missing, idempotency_key_required. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}}},"401":{"description":"Refused. key_expired also includes a `recovery` hint object (`retry_after_seconds`, `do`, `hint`).","headers":{"x-gate-refused":{"description":"One of: bad_key, key_expired, bad_run, bad_user_token. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Refused. This project's AWS Marketplace subscription is inactive. Body is exactly {error: 'aws_subscription_inactive', message}; no x-gate-refused header, and the call is not written to the audit log.","headers":{"x-gate-refused":{"description":"One of: aws_subscription_inactive. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused. action_not_in_run also returns `allowed`, the run's own granted rules, as an array of \"METHOD /path\" strings. model_not_allowed also returns `allowed`, the app's model allow-list.","headers":{"x-gate-refused":{"description":"One of: app_suspended, ip_not_allowed, run_revoked, run_expired, action_not_in_run, run_required, user_tokens_off, outside_user_scope, route_not_allowed, blocked_by_rule, model_not_allowed, bad_action, approval_rejected, approval_expired, check_not_allowed. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Refused. project_not_found carries exactly {error: 'project not found'}, with no x-gate-refused header, before any auth check.","headers":{"x-gate-refused":{"description":"One of: project_not_found, no_such_operation. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Refused. POST .../_gate/recover only; any other method on that path is refused here.","headers":{"x-gate-refused":{"description":"One of: method_not_allowed. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refused. already_executed also returns `outcome_status` (and, on the idempotency-key path, `at`). approval_pending/approval_rejected/approval_expired/bad_action/already_executed also return `action_id`. outcome_unknown also includes a `recovery` hint object (`retry_after_seconds`, `do`, `hint`; `do: call_recover` only when this exact call is itself recoverable).","headers":{"x-gate-refused":{"description":"One of: policy_changed, approval_pending, already_executed, outcome_unknown, approval_mismatch, still_running, no_check, recover_conflict. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Refused. body_too_large is the 10 MB request cap; approval_body_too_large is the 1 MB cap on a body held for approval, before it is resumed with x-odile-action.","headers":{"x-gate-refused":{"description":"One of: body_too_large, approval_body_too_large. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Refused. rate_limited and loop_detected also return `retry_after_seconds` and a matching `retry-after` header; loop_detected also sets `x-odile-gate-loop-detected: true`. call_limit_reached, loop_detected and run_limit_reached also include a `recovery` hint object (`retry_after_seconds`, `do`, `hint`).","headers":{"x-gate-refused":{"description":"One of: call_limit_reached, run_limit_reached, rate_limited, loop_detected, monthly_quota. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}},"Retry-After":{"description":"Delay in seconds for time-based limits (minute, loop or monthly quota), or the upstream Retry-After value. Lifetime app/run allowances do not refill on a timer and omit this header; follow the refusal recovery instructions.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Refused. response_redaction_failed also returns `upstream_status` and a `recovery` object saying the write may already have executed and must not be retried with a new Idempotency-Key.","headers":{"x-gate-refused":{"description":"One of: signing_failed, upstream_timeout, upstream_error, response_redaction_failed. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Refused. signing_key_missing/signing_key_unavailable/signing_failed (502 above) only occur when the SIGNED_REQUESTS env flag is on; it is currently \"0\" (off) per wrangler.toml, so these three are not reachable today.","headers":{"x-gate-refused":{"description":"One of: secret_unavailable, approval_unavailable, signing_key_missing, signing_key_unavailable. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"description":"Forwarded to the upstream exactly as received, any content type, up to 10 MB (1 MB while the call is held for approval and has not yet been resumed with x-odile-action). Ordinary request bodies are not stored, only hashed. Approval holds retain the path, query and body encrypted until a known execution outcome, rejection or expiry cleanup; unknown outcomes retain them pending resolution or expiry cleanup. Gate can inspect request bodies for configured block rules, model limits and required approval fields.","content":{"*/*":{"schema":{"type":"string","format":"binary"}}}}},"patch":{"tags":["Gateway"],"operationId":"gwProxyPatch","summary":"Proxy a PATCH call through Gate to the project's upstream API.","description":"Forwards one call to the project's own upstream API through its allow-list, exactly as the app key's rules permit. This is the one route every Gate app actually calls; everything else in the API manages the project. The {path} segment (which may contain further slashes and a query string) is appended to the project's configured upstream base URL unchanged, except for `/_gate/run`, `/_gate/run/delegate`, `/_gate/actions/{id}` and `/_gate/recover`, which Gate intercepts itself and never forwards (out of scope here; see the Gate Actions/recovery fragment, except for the outcome_unknown recovery flow below, which this fragment documents because it is reached through this same proxy path).\n\nAuth: `Authorization: Bearer <app key>` (gw_... is wrong; app keys match APP_KEY) is required on every call. `x-odile-run` (a Gate Actions run token) is additionally required when the app's run mode is `all`, or `writes` and the method is a write (anything but GET/HEAD/OPTIONS), and is always required on `POST .../_gate/recover`. When a run token is sent, the call must match one of the run's granted actions (and every ancestor run's, for a delegated run) or it is refused with action_not_in_run.\n\nRequest headers Gate reads: `authorization` (the app key), `x-odile-run` (run token), `x-odile-action` (resumes a call that was held for approval, with the action id returned by the 202), `x-odile-user-token` (a signed-in user's JWT, for a route with a {user} or ?key={user} placeholder; needs user_tokens configured on the project or a 403), and `idempotency-key` (required on a write made inside a run, and on `POST .../_gate/recover`, up to 255 characters; a repeat of the same key on the same run gets already_executed or outcome_unknown instead of being resent). Gate also reads `content-length` to pre-check the 10 MB body cap. `x-gate-ip` and `x-gate-country` are set internally by the public worker from the real connecting IP/CF country and are not something a caller sets; any `x-gate-*` header a caller sends is deleted before this Durable Object ever sees it.\n\nHeaders dropped before the call reaches the upstream: hop-by-hop headers (connection, keep-alive, proxy-connection, proxy-authenticate, proxy-authorization, te, trailer, transfer-encoding, upgrade) and anything the client listed in its own Connection header, plus authorization, cookie, host, content-length, expect, forwarded, x-real-ip, true-client-ip, x-http-method-override/x-http-method/x-method-override, x-original-url/x-rewrite-url/x-original-uri/x-original-method, x-odile-user-token, x-odile-run, x-odile-action, and every cf-*, x-forwarded-* and x-gate-* header. The project's own upstream secret header (if configured) is injected here instead. Response headers dropped on the way back: the same hop-by-hop set plus set-cookie (one Gate host serves every project, so an upstream's cookie must never reach another project's caller).\n\nChecks run in this order, each able to refuse the call (reason is the `x-gate-refused` header and the JSON `error` field, both from the GwRefusal values below, unless noted): the project exists (project_not_found, 404, no refusal header, not logged) and is not an inactive AWS Marketplace subscription (aws_subscription_inactive, 402, no `x-gate-refused` header and no audit row at all -- checked again right before the upstream send) -> the app key (bad_key, 401; only the first 20 bad-key calls an hour get an audit row) -> a Pro client-handoff key's expiry/call cap (key_expired 401 / call_limit_reached 429) -> the app is not suspended (app_suspended, 403) -> the caller's IP against the project's allow-list (ip_not_allowed, 403, unless the project is in observe mode, which logs and forwards instead) -> the path has no encoded slash/backslash/dot-segment/control character (unsafe_path, 400) -> the app's own route allow-list and template (route_not_allowed, 403, for a template-refused route or no matching allow-list rule) -> a per-user route's x-odile-user-token (user_tokens_off 403 if the project has none configured; bad_user_token 401 if missing/invalid/expired; outside_user_scope 403 if it names a different user) -> the 10 MB body cap (body_too_large, 413) -> a _method field in the query or in a form, multipart or JSON body (method_override, 403, even when observing: Rails, Laravel and Symfony APIs would run that method instead of the one Gate checked) -> the project's regex block rules over the path, query and whole decoded body (blocked_by_rule, 403, unless observing) -> an app-level model allow-list, read out of the body/query/content-type (model_not_allowed, 403, also on an unreadable body, unless observing) -> the x-odile-run token, if the app's run mode requires one (run_required, 403) or one was sent (bad_run 401 if unknown/other app; run_revoked/run_expired 403 if the run or an ancestor is no longer active; action_not_in_run 403 if this method+path is not one of the run's granted actions, listing the ones that are) -> approval requirements, templated or set on the run action: with no x-odile-action header, the call is held (see 202 below) once its body fits the 1 MB approval cap (approval_body_too_large, 413, otherwise) and carries every field the template requires (required_field_missing, 400); with one, the action must exist (bad_action 403), be approved (approval_pending 409 / approval_rejected 403 / approval_expired 403 / already_executed 409 with its outcome / outcome_unknown 409 if it is mid-flight or unresolved), and match this exact call's method, path+query and forwarded headers and body hash (approval_mismatch, 409) -> a run write's Idempotency-Key (idempotency_key_required 400; already_executed 409 if that key already finished, with its outcome; outcome_unknown 409 if it is in flight or unresolved) -> every ancestor run's own grant and limits (action_not_in_run 403 outside an ancestor grant; run_limit_reached 429 once the run or an ancestor used up its calls) -> the agent loop breaker, which refuses a call repeating the same method+path+query+body hash too many times in its window, or at a too-steady machine cadence (loop_detected, 429, `x-odile-gate-loop-detected: true` and `retry-after`, unless observing) -> the app's per-minute limit (rate_limited, 429, `retry-after`) -> the project's monthly plan quota, unless a prepaid x402 call pack covers it or the plan is Gate's own internal plan (monthly_quota, 429; the message names the extra-call limit on Pro, and mentions buying a pack when X402_PACKS or X402_BEARER_PACKS is enabled) -> decrypting the upstream secret header, if configured (secret_unavailable, 503) -> re-checks of policy/run/approval-expiry/handoff/AWS state taken right before the send, since nothing may await between them and the fetch (policy_changed 409; run_revoked/run_expired 403; approval_expired 403; key_expired/call_limit_reached; aws_subscription_inactive 402) -> request signing, only when the SIGNED_REQUESTS env flag is on (currently \"0\", so these are unreachable today) and this app has signing enabled: signing_key_missing 503 with no active key, signing_key_unavailable 503 if the key cannot be decrypted, signing_failed 502 if signing itself throws (the call is never sent unsigned) -> the upstream fetch, under the project's own timeout (upstream_timeout, 502) or on any fetch error (upstream_error, 502) -> optional response filtering (an admin-set JSON-Pointer allow-list): a non-JSON or malformed upstream body, or one over 1 MB or slower than the redaction timeout, is withheld (response_redaction_failed, 502; a write may already have executed, so the body says not to retry with a new key) -- a policy change caught exactly here reuses the same response_redaction_failed reason even though nothing was actually withheld for redaction, because the upstream call has already been made and cannot be unmade.\n\nA key_expired, call_limit_reached, loop_detected, run_limit_reached or outcome_unknown refusal also carries a `recovery` object (`retry_after_seconds`, `do`: stop/wait_then_retry_once/call_recover/ask_human, `hint`) telling the caller what to do next; `call_recover` is only used for an outcome_unknown write this exact call could recover with POST .../_gate/recover.\n\nA hold for approval answers 202 with action_id, expires_at, a `resume` hint, and (only when the project has a risk model configured) a `risk` score and its top contributing `risk_features`. A plain call that clears every check forwards the upstream's exact status, body and most headers; if response filtering is on, the body is replaced by the selected JSON subtree and the headers are replaced by just content-type, cache-control, x-gate-redacted: allow-list and any CORS headers the upstream sent. Either way Gate appends a `server-timing` header (gate;dur=..., upstream;dur=..., and redaction;dur=... when filtering ran).\n\nRecovery (POST only; always needs x-odile-run and an idempotency-key header naming the write to recover): POST .../_gate/recover asks the run action's configured check (a GET the run itself could make) whether a write with that Idempotency-Key happened, and settles it. Refusals specific to this call: method_not_allowed (405, non-POST), bad_run (401, missing or unknown x-odile-run), idempotency_key_required (400, missing/over 255 chars), no_such_operation (404, no write with that key in this run), still_running (409, the write is still in flight), no_check (409, the run action was granted with no check), check_not_allowed (403, the check path is template-refused or is not itself a read this run/app/user could make), bad_user_token (401, the check reads a per-user route and x-odile-user-token is missing or invalid), rate_limited (429, the check spends the app's per-minute limit like any call), secret_unavailable (503), recover_conflict (409, the write's state changed while Gate was checking), and the same policy_changed/run_revoked/run_expired/aws_subscription_inactive re-checks as above. On success (200, `x-odile-outcome` header, never logged as a refusal): a 404 from the check settles the write as executed (outcome: executed, recovered: true, with a short evidence object when the check returned one); a 404 settles it as safe to retry once, but only when the action was granted with idempotent: true (outcome: not_executed, safe_to_retry: true) -- otherwise it is outcome: needs_review with found: false, since a late-landing write could then run twice; a check with no clear answer (not a 404, and not a JSON list, {data:[...]}, or one object with an id) is also needs_review. A write already marked done answers outcome: executed immediately without calling the check again.\n\nBodies: a write's body is read up to 10 MB (413 past that; 1 MB while an approval is pending and uncommitted); it is forwarded as the exact bytes received (any content type, not just JSON) and is never stored, only hashed, except the 1 MB sealed copy of a body held for approval, whose path, query and body are cleared after a known execution outcome, rejection or expiry cleanup; unknown outcomes retain that content pending resolution or expiry cleanup.","security":[{"appKey":[]},{"appKey":[],"runToken":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"path","in":"path","required":true,"schema":{"type":"string"},"description":"The upstream call, rest-of-path and query string, exactly as it is appended to the project's configured upstream base URL (e.g. 'orders/42?expand=items'), except for the literal values _gate/run, _gate/run/delegate, _gate/actions/{id} and _gate/recover, which Gate handles itself. May contain further slashes; must not contain an encoded slash/backslash, a dot segment, or a control character (refused as unsafe_path)."},{"name":"x-odile-run","in":"header","required":false,"schema":{"type":"string"},"description":"A Gate Actions run token (gr_...). Required when the app's run mode is `all`, or `writes` and this is a write; always required on POST .../_gate/recover."},{"name":"x-odile-action","in":"header","required":false,"schema":{"type":"string"},"description":"The action_id from a prior 202 approval_required response, to resume that exact held call once a person has approved it."},{"name":"x-odile-user-token","in":"header","required":false,"schema":{"type":"string"},"description":"A signed-in end user's JWT (RS256/ES256/EdDSA), required only for a route whose allow-list rule names {user} or a ?key={user} pin, when the project has user_tokens configured."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Required on a write made inside a run (idempotency_key_required if missing), and on POST .../_gate/recover to name the write being recovered. A repeat of the same key on the same run is never resent."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"The upstream's own response, status and body unchanged (or, if the app has response filtering configured, the allow-listed JSON subtree only). Headers are the upstream's own minus hop-by-hop and set-cookie (or, when filtered, just content-type, cache-control, x-gate-redacted and any CORS headers), plus Gate's server-timing header.","headers":{"server-timing":{"schema":{"type":"string"},"description":"gate;dur=<ms>, upstream;dur=<ms>[, redaction;dur=<ms>]"},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"*/*":{"schema":{}}}},"202":{"description":"The call needs approval and has been held; it did not reach the upstream. A person must approve it in the dashboard, then the agent resends the identical call with x-odile-action. Follow Location or status_url with GET using the same app key and the same run token when the held call used one. job_id equals action_id. This is a human approval hold, not automatic background execution. Only x-odile-outcome: approval_required identifies a Gate hold; an upstream API may return an unrelated 202 with its own body and headers.","headers":{"x-odile-outcome":{"schema":{"type":"string","const":"approval_required"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"Location":{"$ref":"#/components/headers/ActionLocation"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/GwApprovalHeld"},{"description":"Unmodified upstream 202 body. Gate does not know its schema, job identity or polling contract."}]}},"*/*":{"schema":{"description":"An upstream 202 may use any media type, or have an empty body. Follow that API's contract."}}},"links":{"actionStatus":{"operationId":"agentGetAction","parameters":{"project_id":"$request.path.project_id","action_id":"$response.body#/action_id"},"description":"Poll the held action using the same app key and run token; wait for human approval before replay."}}},"400":{"description":"Refused. required_field_missing also returns `missing`, an array of the field names the held call's JSON body must carry. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","headers":{"x-gate-refused":{"description":"One of: unsafe_path, required_field_missing, idempotency_key_required. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}}},"401":{"description":"Refused. key_expired also includes a `recovery` hint object (`retry_after_seconds`, `do`, `hint`).","headers":{"x-gate-refused":{"description":"One of: bad_key, key_expired, bad_run, bad_user_token. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Refused. This project's AWS Marketplace subscription is inactive. Body is exactly {error: 'aws_subscription_inactive', message}; no x-gate-refused header, and the call is not written to the audit log.","headers":{"x-gate-refused":{"description":"One of: aws_subscription_inactive. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused. action_not_in_run also returns `allowed`, the run's own granted rules, as an array of \"METHOD /path\" strings. model_not_allowed also returns `allowed`, the app's model allow-list.","headers":{"x-gate-refused":{"description":"One of: app_suspended, ip_not_allowed, run_revoked, run_expired, action_not_in_run, run_required, user_tokens_off, outside_user_scope, route_not_allowed, blocked_by_rule, model_not_allowed, bad_action, approval_rejected, approval_expired, check_not_allowed. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Refused. project_not_found carries exactly {error: 'project not found'}, with no x-gate-refused header, before any auth check.","headers":{"x-gate-refused":{"description":"One of: project_not_found, no_such_operation. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Refused. POST .../_gate/recover only; any other method on that path is refused here.","headers":{"x-gate-refused":{"description":"One of: method_not_allowed. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refused. already_executed also returns `outcome_status` (and, on the idempotency-key path, `at`). approval_pending/approval_rejected/approval_expired/bad_action/already_executed also return `action_id`. outcome_unknown also includes a `recovery` hint object (`retry_after_seconds`, `do`, `hint`; `do: call_recover` only when this exact call is itself recoverable).","headers":{"x-gate-refused":{"description":"One of: policy_changed, approval_pending, already_executed, outcome_unknown, approval_mismatch, still_running, no_check, recover_conflict. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Refused. body_too_large is the 10 MB request cap; approval_body_too_large is the 1 MB cap on a body held for approval, before it is resumed with x-odile-action.","headers":{"x-gate-refused":{"description":"One of: body_too_large, approval_body_too_large. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Refused. rate_limited and loop_detected also return `retry_after_seconds` and a matching `retry-after` header; loop_detected also sets `x-odile-gate-loop-detected: true`. call_limit_reached, loop_detected and run_limit_reached also include a `recovery` hint object (`retry_after_seconds`, `do`, `hint`).","headers":{"x-gate-refused":{"description":"One of: call_limit_reached, run_limit_reached, rate_limited, loop_detected, monthly_quota. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}},"Retry-After":{"description":"Delay in seconds for time-based limits (minute, loop or monthly quota), or the upstream Retry-After value. Lifetime app/run allowances do not refill on a timer and omit this header; follow the refusal recovery instructions.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Refused. response_redaction_failed also returns `upstream_status` and a `recovery` object saying the write may already have executed and must not be retried with a new Idempotency-Key.","headers":{"x-gate-refused":{"description":"One of: signing_failed, upstream_timeout, upstream_error, response_redaction_failed. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Refused. signing_key_missing/signing_key_unavailable/signing_failed (502 above) only occur when the SIGNED_REQUESTS env flag is on; it is currently \"0\" (off) per wrangler.toml, so these three are not reachable today.","headers":{"x-gate-refused":{"description":"One of: secret_unavailable, approval_unavailable, signing_key_missing, signing_key_unavailable. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"description":"Forwarded to the upstream exactly as received, any content type, up to 10 MB (1 MB while the call is held for approval and has not yet been resumed with x-odile-action). Ordinary request bodies are not stored, only hashed. Approval holds retain the path, query and body encrypted until a known execution outcome, rejection or expiry cleanup; unknown outcomes retain them pending resolution or expiry cleanup. Gate can inspect request bodies for configured block rules, model limits and required approval fields.","content":{"*/*":{"schema":{"type":"string","format":"binary"}}}}},"delete":{"tags":["Gateway"],"operationId":"gwProxyDelete","summary":"Proxy a DELETE call through Gate to the project's upstream API.","description":"Forwards one call to the project's own upstream API through its allow-list, exactly as the app key's rules permit. This is the one route every Gate app actually calls; everything else in the API manages the project. The {path} segment (which may contain further slashes and a query string) is appended to the project's configured upstream base URL unchanged, except for `/_gate/run`, `/_gate/run/delegate`, `/_gate/actions/{id}` and `/_gate/recover`, which Gate intercepts itself and never forwards (out of scope here; see the Gate Actions/recovery fragment, except for the outcome_unknown recovery flow below, which this fragment documents because it is reached through this same proxy path).\n\nAuth: `Authorization: Bearer <app key>` (gw_... is wrong; app keys match APP_KEY) is required on every call. `x-odile-run` (a Gate Actions run token) is additionally required when the app's run mode is `all`, or `writes` and the method is a write (anything but GET/HEAD/OPTIONS), and is always required on `POST .../_gate/recover`. When a run token is sent, the call must match one of the run's granted actions (and every ancestor run's, for a delegated run) or it is refused with action_not_in_run.\n\nRequest headers Gate reads: `authorization` (the app key), `x-odile-run` (run token), `x-odile-action` (resumes a call that was held for approval, with the action id returned by the 202), `x-odile-user-token` (a signed-in user's JWT, for a route with a {user} or ?key={user} placeholder; needs user_tokens configured on the project or a 403), and `idempotency-key` (required on a write made inside a run, and on `POST .../_gate/recover`, up to 255 characters; a repeat of the same key on the same run gets already_executed or outcome_unknown instead of being resent). Gate also reads `content-length` to pre-check the 10 MB body cap. `x-gate-ip` and `x-gate-country` are set internally by the public worker from the real connecting IP/CF country and are not something a caller sets; any `x-gate-*` header a caller sends is deleted before this Durable Object ever sees it.\n\nHeaders dropped before the call reaches the upstream: hop-by-hop headers (connection, keep-alive, proxy-connection, proxy-authenticate, proxy-authorization, te, trailer, transfer-encoding, upgrade) and anything the client listed in its own Connection header, plus authorization, cookie, host, content-length, expect, forwarded, x-real-ip, true-client-ip, x-http-method-override/x-http-method/x-method-override, x-original-url/x-rewrite-url/x-original-uri/x-original-method, x-odile-user-token, x-odile-run, x-odile-action, and every cf-*, x-forwarded-* and x-gate-* header. The project's own upstream secret header (if configured) is injected here instead. Response headers dropped on the way back: the same hop-by-hop set plus set-cookie (one Gate host serves every project, so an upstream's cookie must never reach another project's caller).\n\nChecks run in this order, each able to refuse the call (reason is the `x-gate-refused` header and the JSON `error` field, both from the GwRefusal values below, unless noted): the project exists (project_not_found, 404, no refusal header, not logged) and is not an inactive AWS Marketplace subscription (aws_subscription_inactive, 402, no `x-gate-refused` header and no audit row at all -- checked again right before the upstream send) -> the app key (bad_key, 401; only the first 20 bad-key calls an hour get an audit row) -> a Pro client-handoff key's expiry/call cap (key_expired 401 / call_limit_reached 429) -> the app is not suspended (app_suspended, 403) -> the caller's IP against the project's allow-list (ip_not_allowed, 403, unless the project is in observe mode, which logs and forwards instead) -> the path has no encoded slash/backslash/dot-segment/control character (unsafe_path, 400) -> the app's own route allow-list and template (route_not_allowed, 403, for a template-refused route or no matching allow-list rule) -> a per-user route's x-odile-user-token (user_tokens_off 403 if the project has none configured; bad_user_token 401 if missing/invalid/expired; outside_user_scope 403 if it names a different user) -> the 10 MB body cap (body_too_large, 413) -> a _method field in the query or in a form, multipart or JSON body (method_override, 403, even when observing: Rails, Laravel and Symfony APIs would run that method instead of the one Gate checked) -> the project's regex block rules over the path, query and whole decoded body (blocked_by_rule, 403, unless observing) -> an app-level model allow-list, read out of the body/query/content-type (model_not_allowed, 403, also on an unreadable body, unless observing) -> the x-odile-run token, if the app's run mode requires one (run_required, 403) or one was sent (bad_run 401 if unknown/other app; run_revoked/run_expired 403 if the run or an ancestor is no longer active; action_not_in_run 403 if this method+path is not one of the run's granted actions, listing the ones that are) -> approval requirements, templated or set on the run action: with no x-odile-action header, the call is held (see 202 below) once its body fits the 1 MB approval cap (approval_body_too_large, 413, otherwise) and carries every field the template requires (required_field_missing, 400); with one, the action must exist (bad_action 403), be approved (approval_pending 409 / approval_rejected 403 / approval_expired 403 / already_executed 409 with its outcome / outcome_unknown 409 if it is mid-flight or unresolved), and match this exact call's method, path+query and forwarded headers and body hash (approval_mismatch, 409) -> a run write's Idempotency-Key (idempotency_key_required 400; already_executed 409 if that key already finished, with its outcome; outcome_unknown 409 if it is in flight or unresolved) -> every ancestor run's own grant and limits (action_not_in_run 403 outside an ancestor grant; run_limit_reached 429 once the run or an ancestor used up its calls) -> the agent loop breaker, which refuses a call repeating the same method+path+query+body hash too many times in its window, or at a too-steady machine cadence (loop_detected, 429, `x-odile-gate-loop-detected: true` and `retry-after`, unless observing) -> the app's per-minute limit (rate_limited, 429, `retry-after`) -> the project's monthly plan quota, unless a prepaid x402 call pack covers it or the plan is Gate's own internal plan (monthly_quota, 429; the message names the extra-call limit on Pro, and mentions buying a pack when X402_PACKS or X402_BEARER_PACKS is enabled) -> decrypting the upstream secret header, if configured (secret_unavailable, 503) -> re-checks of policy/run/approval-expiry/handoff/AWS state taken right before the send, since nothing may await between them and the fetch (policy_changed 409; run_revoked/run_expired 403; approval_expired 403; key_expired/call_limit_reached; aws_subscription_inactive 402) -> request signing, only when the SIGNED_REQUESTS env flag is on (currently \"0\", so these are unreachable today) and this app has signing enabled: signing_key_missing 503 with no active key, signing_key_unavailable 503 if the key cannot be decrypted, signing_failed 502 if signing itself throws (the call is never sent unsigned) -> the upstream fetch, under the project's own timeout (upstream_timeout, 502) or on any fetch error (upstream_error, 502) -> optional response filtering (an admin-set JSON-Pointer allow-list): a non-JSON or malformed upstream body, or one over 1 MB or slower than the redaction timeout, is withheld (response_redaction_failed, 502; a write may already have executed, so the body says not to retry with a new key) -- a policy change caught exactly here reuses the same response_redaction_failed reason even though nothing was actually withheld for redaction, because the upstream call has already been made and cannot be unmade.\n\nA key_expired, call_limit_reached, loop_detected, run_limit_reached or outcome_unknown refusal also carries a `recovery` object (`retry_after_seconds`, `do`: stop/wait_then_retry_once/call_recover/ask_human, `hint`) telling the caller what to do next; `call_recover` is only used for an outcome_unknown write this exact call could recover with POST .../_gate/recover.\n\nA hold for approval answers 202 with action_id, expires_at, a `resume` hint, and (only when the project has a risk model configured) a `risk` score and its top contributing `risk_features`. A plain call that clears every check forwards the upstream's exact status, body and most headers; if response filtering is on, the body is replaced by the selected JSON subtree and the headers are replaced by just content-type, cache-control, x-gate-redacted: allow-list and any CORS headers the upstream sent. Either way Gate appends a `server-timing` header (gate;dur=..., upstream;dur=..., and redaction;dur=... when filtering ran).\n\nRecovery (POST only; always needs x-odile-run and an idempotency-key header naming the write to recover): POST .../_gate/recover asks the run action's configured check (a GET the run itself could make) whether a write with that Idempotency-Key happened, and settles it. Refusals specific to this call: method_not_allowed (405, non-POST), bad_run (401, missing or unknown x-odile-run), idempotency_key_required (400, missing/over 255 chars), no_such_operation (404, no write with that key in this run), still_running (409, the write is still in flight), no_check (409, the run action was granted with no check), check_not_allowed (403, the check path is template-refused or is not itself a read this run/app/user could make), bad_user_token (401, the check reads a per-user route and x-odile-user-token is missing or invalid), rate_limited (429, the check spends the app's per-minute limit like any call), secret_unavailable (503), recover_conflict (409, the write's state changed while Gate was checking), and the same policy_changed/run_revoked/run_expired/aws_subscription_inactive re-checks as above. On success (200, `x-odile-outcome` header, never logged as a refusal): a 404 from the check settles the write as executed (outcome: executed, recovered: true, with a short evidence object when the check returned one); a 404 settles it as safe to retry once, but only when the action was granted with idempotent: true (outcome: not_executed, safe_to_retry: true) -- otherwise it is outcome: needs_review with found: false, since a late-landing write could then run twice; a check with no clear answer (not a 404, and not a JSON list, {data:[...]}, or one object with an id) is also needs_review. A write already marked done answers outcome: executed immediately without calling the check again.\n\nBodies: a write's body is read up to 10 MB (413 past that; 1 MB while an approval is pending and uncommitted); it is forwarded as the exact bytes received (any content type, not just JSON) and is never stored, only hashed, except the 1 MB sealed copy of a body held for approval, whose path, query and body are cleared after a known execution outcome, rejection or expiry cleanup; unknown outcomes retain that content pending resolution or expiry cleanup.","security":[{"appKey":[]},{"appKey":[],"runToken":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"path","in":"path","required":true,"schema":{"type":"string"},"description":"The upstream call, rest-of-path and query string, exactly as it is appended to the project's configured upstream base URL (e.g. 'orders/42?expand=items'), except for the literal values _gate/run, _gate/run/delegate, _gate/actions/{id} and _gate/recover, which Gate handles itself. May contain further slashes; must not contain an encoded slash/backslash, a dot segment, or a control character (refused as unsafe_path)."},{"name":"x-odile-run","in":"header","required":false,"schema":{"type":"string"},"description":"A Gate Actions run token (gr_...). Required when the app's run mode is `all`, or `writes` and this is a write; always required on POST .../_gate/recover."},{"name":"x-odile-action","in":"header","required":false,"schema":{"type":"string"},"description":"The action_id from a prior 202 approval_required response, to resume that exact held call once a person has approved it."},{"name":"x-odile-user-token","in":"header","required":false,"schema":{"type":"string"},"description":"A signed-in end user's JWT (RS256/ES256/EdDSA), required only for a route whose allow-list rule names {user} or a ?key={user} pin, when the project has user_tokens configured."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Required on a write made inside a run (idempotency_key_required if missing), and on POST .../_gate/recover to name the write being recovered. A repeat of the same key on the same run is never resent."},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"The upstream's own response, status and body unchanged (or, if the app has response filtering configured, the allow-listed JSON subtree only). Headers are the upstream's own minus hop-by-hop and set-cookie (or, when filtered, just content-type, cache-control, x-gate-redacted and any CORS headers), plus Gate's server-timing header.","headers":{"server-timing":{"schema":{"type":"string"},"description":"gate;dur=<ms>, upstream;dur=<ms>[, redaction;dur=<ms>]"},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"*/*":{"schema":{}}}},"202":{"description":"The call needs approval and has been held; it did not reach the upstream. A person must approve it in the dashboard, then the agent resends the identical call with x-odile-action. Follow Location or status_url with GET using the same app key and the same run token when the held call used one. job_id equals action_id. This is a human approval hold, not automatic background execution. Only x-odile-outcome: approval_required identifies a Gate hold; an upstream API may return an unrelated 202 with its own body and headers.","headers":{"x-odile-outcome":{"schema":{"type":"string","const":"approval_required"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"Location":{"$ref":"#/components/headers/ActionLocation"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/GwApprovalHeld"},{"description":"Unmodified upstream 202 body. Gate does not know its schema, job identity or polling contract."}]}},"*/*":{"schema":{"description":"An upstream 202 may use any media type, or have an empty body. Follow that API's contract."}}},"links":{"actionStatus":{"operationId":"agentGetAction","parameters":{"project_id":"$request.path.project_id","action_id":"$response.body#/action_id"},"description":"Poll the held action using the same app key and run token; wait for human approval before replay."}}},"400":{"description":"Refused. required_field_missing also returns `missing`, an array of the field names the held call's JSON body must carry. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","headers":{"x-gate-refused":{"description":"One of: unsafe_path, required_field_missing, idempotency_key_required. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}}},"401":{"description":"Refused. key_expired also includes a `recovery` hint object (`retry_after_seconds`, `do`, `hint`).","headers":{"x-gate-refused":{"description":"One of: bad_key, key_expired, bad_run, bad_user_token. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Refused. This project's AWS Marketplace subscription is inactive. Body is exactly {error: 'aws_subscription_inactive', message}; no x-gate-refused header, and the call is not written to the audit log.","headers":{"x-gate-refused":{"description":"One of: aws_subscription_inactive. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused. action_not_in_run also returns `allowed`, the run's own granted rules, as an array of \"METHOD /path\" strings. model_not_allowed also returns `allowed`, the app's model allow-list.","headers":{"x-gate-refused":{"description":"One of: app_suspended, ip_not_allowed, run_revoked, run_expired, action_not_in_run, run_required, user_tokens_off, outside_user_scope, route_not_allowed, blocked_by_rule, model_not_allowed, bad_action, approval_rejected, approval_expired, check_not_allowed. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Refused. project_not_found carries exactly {error: 'project not found'}, with no x-gate-refused header, before any auth check.","headers":{"x-gate-refused":{"description":"One of: project_not_found, no_such_operation. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Refused. POST .../_gate/recover only; any other method on that path is refused here.","headers":{"x-gate-refused":{"description":"One of: method_not_allowed. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refused. already_executed also returns `outcome_status` (and, on the idempotency-key path, `at`). approval_pending/approval_rejected/approval_expired/bad_action/already_executed also return `action_id`. outcome_unknown also includes a `recovery` hint object (`retry_after_seconds`, `do`, `hint`; `do: call_recover` only when this exact call is itself recoverable).","headers":{"x-gate-refused":{"description":"One of: policy_changed, approval_pending, already_executed, outcome_unknown, approval_mismatch, still_running, no_check, recover_conflict. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Refused. body_too_large is the 10 MB request cap; approval_body_too_large is the 1 MB cap on a body held for approval, before it is resumed with x-odile-action.","headers":{"x-gate-refused":{"description":"One of: body_too_large, approval_body_too_large. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Refused. rate_limited and loop_detected also return `retry_after_seconds` and a matching `retry-after` header; loop_detected also sets `x-odile-gate-loop-detected: true`. call_limit_reached, loop_detected and run_limit_reached also include a `recovery` hint object (`retry_after_seconds`, `do`, `hint`).","headers":{"x-gate-refused":{"description":"One of: call_limit_reached, run_limit_reached, rate_limited, loop_detected, monthly_quota. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}},"Retry-After":{"description":"Delay in seconds for time-based limits (minute, loop or monthly quota), or the upstream Retry-After value. Lifetime app/run allowances do not refill on a timer and omit this header; follow the refusal recovery instructions.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Refused. response_redaction_failed also returns `upstream_status` and a `recovery` object saying the write may already have executed and must not be retried with a new Idempotency-Key.","headers":{"x-gate-refused":{"description":"One of: signing_failed, upstream_timeout, upstream_error, response_redaction_failed. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Refused. signing_key_missing/signing_key_unavailable/signing_failed (502 above) only occur when the SIGNED_REQUESTS env flag is on; it is currently \"0\" (off) per wrangler.toml, so these three are not reachable today.","headers":{"x-gate-refused":{"description":"One of: secret_unavailable, approval_unavailable, signing_key_missing, signing_key_unavailable. Absent on project_not_found and aws_subscription_inactive, which carry no x-gate-refused header and are not audited.","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"description":"Forwarded to the upstream exactly as received, any content type, up to 10 MB (1 MB while the call is held for approval and has not yet been resumed with x-odile-action). Ordinary request bodies are not stored, only hashed. Approval holds retain the path, query and body encrypted until a known execution outcome, rejection or expiry cleanup; unknown outcomes retain them pending resolution or expiry cleanup. Gate can inspect request bodies for configured block rules, model limits and required approval fields.","content":{"*/*":{"schema":{"type":"string","format":"binary"}}}}}},"/g/{project_id}/_gate/run":{"get":{"tags":["Agent run endpoints"],"operationId":"agentGetRun","summary":"What this run still allows","description":"Returns the run's scope, expiry, remaining calls and each granted action (rule, approval_required, calls_left, recoverable), plus the run state. GET only (other methods: 405 method_not_allowed). Needs the run token in x-odile-run.","security":[{"appKey":[],"runToken":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"The run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRun"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}}},"401":{"description":"bad_key (app key) or bad_run (missing or unknown run token).","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"method_not_allowed: GET only.","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/g/{project_id}/_gate/actions/{action_id}":{"get":{"tags":["Agent run endpoints"],"operationId":"agentGetAction","summary":"Where one held action stands","description":"For a call held for approval (202 approval_required gave its action id): its state (pending, approved, rejected, expired, executing, executed, unknown), the upstream status once it ran, and its expiry. Looked up within this run, or within the app when no run token is sent. GET only.","security":[{"appKey":[]},{"appKey":[],"runToken":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"action_id","in":"path","required":true,"schema":{"type":"string","pattern":"^act_[0-9a-f]{16}$"}},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"The action.","content":{"application/json":{"schema":{"type":"object","properties":{"action_id":{"type":"string"},"state":{"type":"string","enum":["pending","approved","rejected","expired","executing","executed","unknown"]},"outcome_status":{"type":["integer","null"]},"expires_at":{"type":"string","format":"date-time"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}}},"401":{"description":"bad_key, or bad_run when a run token was sent but not accepted.","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"bad_action: no action with that id in this run.","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"method_not_allowed: GET only.","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/g/{project_id}/_gate/recover":{"post":{"tags":["Agent run endpoints"],"operationId":"agentRecover","summary":"Find out whether a write whose answer was lost actually ran","description":"After a write in a run got 409 outcome_unknown (the upstream timed out or answered 5xx after Gate sent it), call this with the run token and the SAME Idempotency-Key. Gate runs the action's check (granted as check: \"GET /path?idempotency_key={key}\"; it must be a GET this run may make itself and it spends the app's per-minute limit) against your API and answers: executed (found; do not send it again, a retry gets already_executed; evidence is the found record, up to 2 KB, unless response filtering is on), not_executed with safe_to_retry (not found AND the action was granted with idempotent: true; the call budget is refunded; resend once with the same key), or needs_review (not found but not idempotent, or no clear answer: a person must look). A 404 from the check means not found; a JSON list, {data:[...]} or one object with an id is a clear answer. The outcome is also in the x-odile-outcome header.","security":[{"appKey":[],"runToken":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"Idempotency-Key","in":"header","required":true,"description":"The key of the write to recover (up to 255 characters).","schema":{"type":"string","maxLength":255}},{"name":"x-odile-user-token","in":"header","required":false,"description":"Needed when the check reads a per-user route.","schema":{"type":"string"}},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"An answer about the write.","headers":{"x-odile-outcome":{"schema":{"type":"string","enum":["executed","not_executed","needs_review"]}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["executed","not_executed","needs_review"]},"status":{"type":["integer","null"],"description":"executed earlier with a known upstream status"},"at":{"type":"string","format":"date-time"},"recovered":{"type":"boolean"},"check_status":{"type":["integer","null"]},"evidence":{"description":"The record the check found (omitted with response filtering)."},"found":{"type":"boolean"},"safe_to_retry":{"type":"boolean"},"next":{"type":"string"},"error":{"type":"string"}},"required":["outcome"]}}}},"400":{"description":"idempotency_key_required, or unsafe_path (the filled-in check path leaves the upstream). Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}}},"401":{"description":"bad_key, bad_run (send the run token), or bad_user_token (the check reads a per-user route).","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"run_revoked / run_expired or another inactive-run reason, check_not_allowed (the check is not a GET this run may make), or a handoff/suspension refusal.","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"no_such_operation: no write with this Idempotency-Key in this run.","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"method_not_allowed: POST only.","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"still_running (the write is still waiting on the upstream; ask again in a few seconds), no_check (the action was granted without a check), policy_changed, or recover_conflict (the write changed while Gate checked; ask again).","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the check counts against the app's per-minute limit.","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}},"Retry-After":{"description":"Delay in seconds for time-based limits (minute, loop or monthly quota), or the upstream Retry-After value. Lifetime app/run allowances do not refill on a timer and omit this header; follow the refusal recovery instructions.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"secret_unavailable: the upstream secret could not be decrypted; nothing was checked.","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/g/{project_id}/_gate/run/delegate":{"post":{"tags":["Agent run endpoints"],"operationId":"agentDelegateRun","summary":"Hand part of a run to another app (sub-agent)","description":"Creates a child run for another app in the same project, from inside a run. The child inherits the parent scope (a different scope is refused), its actions must narrow the parent's and keep its approval holds, the child app must allow every delegated route, max_calls must fit the remaining ancestor budget, expiry is capped by the parent, at most five levels deep, and recovery settings (check, idempotent) are inherited, not set. Returns the child token once.","security":[{"appKey":[],"runToken":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The same run specification as POST /api/projects/{project_id}/runs (app, actions, ttl_seconds, max_calls, label), without check/idempotent; scope is inherited.","properties":{"app":{"type":"string"},"actions":{"type":"array","items":{"type":"object"}},"ttl_seconds":{"type":"integer"},"max_calls":{"type":["integer","null"]},"label":{"type":"string"},"scope":{"type":"object","description":"Optional; must equal the parent scope."}},"required":["app","actions"]}}}},"responses":{"201":{"description":"The child run. The token is shown once.","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"gr_... child run token"},"run":{"$ref":"#/components/schemas/AgentRun"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}}},"400":{"description":"bad_delegation: not JSON, a different scope, an invalid run specification, or check/idempotent set on a child action. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}}},"401":{"description":"bad_key or bad_run (send the parent run token with its app key).","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"bad_delegation (actions do not narrow the parent, or the budget does not fit), route_not_allowed (the child app does not allow a delegated route), delegation_depth, app_suspended, or an inactive-run reason.","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"bad_delegation: no active app with that id in this project.","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"method_not_allowed: POST only.","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"approver_required: add an approver before granting approval actions.","headers":{"x-gate-refused":{"description":"The refusal reason (see GwRefusal).","schema":{"$ref":"#/components/schemas/GwRefusal"}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"},"RateLimit-Limit":{"description":"Configured app calls per UTC minute; emitted after an active app key is authenticated.","schema":{"type":"integer","minimum":1}},"RateLimit-Remaining":{"description":"Calls remaining in this app minute counter, clamped to zero. Other quotas and policy checks still apply.","schema":{"type":"integer","minimum":0}},"RateLimit-Reset":{"description":"Seconds until the next UTC minute boundary.","schema":{"type":"integer","minimum":1,"maximum":60}},"RateLimit":{"description":"App-minute remaining count and reset delay, structured as \"app-minute\";r=<remaining>;t=<seconds>.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"App-minute policy: \"app-minute\";q=<per_minute>;w=60.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/projects/{project_id}/apps/{app_id}/routes":{"post":{"tags":["Apps"],"operationId":"appsAddRoute","summary":"Add one exact route to an app's allow-list","description":"Requires explicit confirmation. The rule is one method and a literal path: no * method or segment, no :param or {user} segment, no query pin. Adds nothing if the route is already allowed. Leaves the app's other routes and its per_minute unchanged. Bumps the app's policy version so the route takes effect immediately.","security":[{"adminKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/AppId"},{"$ref":"#/components/parameters/GateVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirm","rule"],"properties":{"confirm":{"type":"boolean","const":true},"rule":{"type":"string","examples":["POST /ops/lines/web-talk"]}}}}}},"responses":{"200":{"description":"The route is allowed","content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string"},"added":{"type":"boolean"},"rule":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Confirmation missing or the rule is not one exact route Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"Bad admin key","headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"No active app with that id","headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}}}},"/mcp/setup":{"post":{"tags":["Public and account"],"operationId":"pubMcpCallSetup","summary":"Gate MCP setup (POST)","description":"Stateless Streamable-HTTP MCP endpoint at https://gate.odilelabs.com/mcp/setup. No install or separate connection key. Existing-project tools require a project key. Supports MCP 2026-07-28 plus legacy 2025-06-18/2025-03-26/2024-11-05. Modern requests are single JSON-RPC 2.0 messages with per-request protocolVersion and clientCapabilities in params._meta, matching MCP-Protocol-Version and Mcp-Method headers, and Mcp-Name for tools/call. server/discover is available to both eras and returns supportedVersions, tools capabilities, instructions, resultType:complete, serverInfo metadata and public cache hints (ttlMs:300000). Modern tools/list and tools/call need no initialize; every modern result includes resultType:complete and serverInfo metadata, and tools/list has the same public cache hints. Tools are ordered consistently and vary only with deployment flags. Modern initialize, notifications/initialized, ping and logging/setLevel are removed. Legacy initialize still negotiates only the original three versions (including fallback to 2025-06-18 for a 2025-11-25 request), and legacy ping, batches and notification acknowledgments retain their previous behavior. No Mcp-Session-Id is issued. Request body is capped at 64 KB and must be valid JSON. Every tool call re-enters this same Worker's own public HTTP API internally (so project creation limits, plan limits and the admin audit log see it exactly as a direct API call would), tagged with x-gate-via: mcp and the caller's real cf-connecting-ip. Create and configure projects, apps, keys, models, response fields, members and dedicated approvers. Three grouped tools select exactly one operation: gate_manage_app_key (rotate/revoke), gate_configure_app (models/runs/response/add_route), gate_manage_members (invite/list/revoke). Lists 12 tools, plus gate_validate_config and gate_sync_declarative when CONFIG_GATEWAY_UPGRADE=1 (14 maximum). gate_update_project updates only the existing project alert threshold and idle-app window through PUT /api/projects/{pid}/alerts; it cannot rename or delete projects. OpenShell setup and usage email configuration remain callable but unlisted; email still requires USAGE_ALERTS=1. The old approver creation name remains callable. Listed tools (when enabled): gate_create_project, gate_update_project, gate_create_app, gate_list_apps, gate_manage_app_key, gate_configure_app, gate_check_setup, gate_create_approver, gate_list_approvers, gate_revoke_approver, gate_list_actions, gate_manage_members, gate_validate_config, gate_sync_declarative. Only capabilities available on this profile are callable; other tools return -32602. A person with an approver key approves or rejects held actions in the dashboard; no MCP tool can approve. Both profiles list apps, dedicated approvers and held actions; old names and verb-first aliases for offered capabilities remain callable, including original names behind grouped tools. Dedicated server card: /mcp/setup/server-card. Use /mcp for the original full compatibility catalog. Existing project operations forward the supplied project key through the same REST authorization checks; discovery needs no project key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubMcpRequest"}}}},"responses":{"200":{"description":"One JSON-RPC response; legacy batches return an array. Modern results include resultType and serverInfo metadata. Existing legacy response bodies are unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubMcpResponse"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"202":{"description":"Legacy-only notifications receive an empty acknowledgment. Modern removed notifications are rejected. Empty acknowledgment only: no job_id, status_url, Location or polling operation.","content":{},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Invalid JSON; or modern validation failure: -32600 for malformed requests/ids or batches, -32602 for missing required per-request metadata, -32020 for missing/mismatched/malformed standard headers, -32022 Unsupported protocol version with data.supported and data.requested. Legacy per-message invalid-request errors retain HTTP200. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PubMcpJsonRpcError"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Modern unknown or removed RPC method: JSON-RPC -32601 (Method not found). Legacy method-not-found errors retain HTTP200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubMcpJsonRpcError"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"413":{"description":"Request body exceeds 64 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubMcpJsonRpcError"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[],"parameters":[{"$ref":"#/components/parameters/GateVersion"}]},"get":{"tags":["Public and account"],"operationId":"pubMcpInfoSetup","summary":"Gate MCP setup (GET)","description":"This server only answers JSON-RPC over POST; it does not open an SSE stream on GET. A GET with an Accept header containing text/html (a browser) 302-redirects to /#mcp on the site. Any other GET (a plain HTTP client, most MCP SDKs probing capabilities) gets 405 with an Allow: POST header. Any HTTP method other than GET/POST on this path also gets a bare 405 with Allow: POST (same route handler, the shared profile handler).","responses":{"302":{"description":"Browser GET (Accept: text/html): redirected to the human docs.","headers":{"Location":{"schema":{"type":"string","enum":["/#mcp"]}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"405":{"description":"Non-browser GET, or any method other than GET/POST. These two cases have different bodies (checked in handleMcp): a non-browser GET gets a JSON body {\"error\":\"POST JSON-RPC messages to this URL\"}; any other method (PUT, DELETE, PATCH, HEAD, OPTIONS) gets `new Response(null, {status:405, headers:{allow:'POST'}})` -- no body and no content-type header at all, not JSON. The content schema below applies only to the non-browser-GET case.","headers":{"Allow":{"schema":{"type":"string","enum":["POST"]}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[],"parameters":[{"$ref":"#/components/parameters/GateVersion"}]}},"/mcp/oversight":{"post":{"tags":["Public and account"],"operationId":"pubMcpCallOversight","summary":"Gate MCP oversight (POST)","description":"Stateless Streamable-HTTP MCP endpoint at https://gate.odilelabs.com/mcp/oversight. No install or separate connection key. Existing-project tools require a project key. Supports MCP 2026-07-28 plus legacy 2025-06-18/2025-03-26/2024-11-05. Modern requests are single JSON-RPC 2.0 messages with per-request protocolVersion and clientCapabilities in params._meta, matching MCP-Protocol-Version and Mcp-Method headers, and Mcp-Name for tools/call. server/discover is available to both eras and returns supportedVersions, tools capabilities, instructions, resultType:complete, serverInfo metadata and public cache hints (ttlMs:300000). Modern tools/list and tools/call need no initialize; every modern result includes resultType:complete and serverInfo metadata, and tools/list has the same public cache hints. Tools are ordered consistently and vary only with deployment flags. Modern initialize, notifications/initialized, ping and logging/setLevel are removed. Legacy initialize still negotiates only the original three versions (including fallback to 2025-06-18 for a 2025-11-25 request), and legacy ping, batches and notification acknowledgments retain their previous behavior. No Mcp-Session-Id is issued. Request body is capped at 64 KB and must be valid JSON. Every tool call re-enters this same Worker's own public HTTP API internally (so project creation limits, plan limits and the admin audit log see it exactly as a direct API call would), tagged with x-gate-via: mcp and the caller's real cf-connecting-ip. Watch and manage existing projects: runs, delegation/revocation, held actions, audit, proof/verification, metrics, timelines/trees, refusal explanations and learning. Lists 15 tools with all flag combinations, including read-only app and dedicated-approver lookup. Listed tools (when enabled): gate_list_apps, gate_list_approvers, gate_create_run, gate_delegate_run, gate_revoke_run, gate_list_actions, gate_read_audit, gate_export_audit_proof, gate_verify_audit_proof, gate_get_metrics, gate_get_run_timeline, gate_get_run_tree, gate_explain_refusal, gate_learn_suggestions, gate_update_app. Only capabilities available on this profile are callable; other tools return -32602. A person with an approver key approves or rejects held actions in the dashboard; no MCP tool can approve. Both profiles list apps, dedicated approvers and held actions; old names and verb-first aliases for offered capabilities remain callable, including original names behind grouped tools. Dedicated server card: /mcp/oversight/server-card. Use /mcp for the original full compatibility catalog. Existing project operations forward the supplied project key through the same REST authorization checks; discovery needs no project key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubMcpRequest"}}}},"responses":{"200":{"description":"One JSON-RPC response; legacy batches return an array. Modern results include resultType and serverInfo metadata. Existing legacy response bodies are unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubMcpResponse"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"202":{"description":"Legacy-only notifications receive an empty acknowledgment. Modern removed notifications are rejected. Empty acknowledgment only: no job_id, status_url, Location or polling operation.","content":{},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Invalid JSON; or modern validation failure: -32600 for malformed requests/ids or batches, -32602 for missing required per-request metadata, -32020 for missing/mismatched/malformed standard headers, -32022 Unsupported protocol version with data.supported and data.requested. Legacy per-message invalid-request errors retain HTTP200. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PubMcpJsonRpcError"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Modern unknown or removed RPC method: JSON-RPC -32601 (Method not found). Legacy method-not-found errors retain HTTP200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubMcpJsonRpcError"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"413":{"description":"Request body exceeds 64 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubMcpJsonRpcError"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"security":[],"parameters":[{"$ref":"#/components/parameters/GateVersion"}]},"get":{"tags":["Public and account"],"operationId":"pubMcpInfoOversight","summary":"Gate MCP oversight (GET)","description":"This server only answers JSON-RPC over POST; it does not open an SSE stream on GET. A GET with an Accept header containing text/html (a browser) 302-redirects to /#mcp on the site. Any other GET (a plain HTTP client, most MCP SDKs probing capabilities) gets 405 with an Allow: POST header. Any HTTP method other than GET/POST on this path also gets a bare 405 with Allow: POST (same route handler, the shared profile handler).","responses":{"302":{"description":"Browser GET (Accept: text/html): redirected to the human docs.","headers":{"Location":{"schema":{"type":"string","enum":["/#mcp"]}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"405":{"description":"Non-browser GET, or any method other than GET/POST. These two cases have different bodies (checked in handleMcp): a non-browser GET gets a JSON body {\"error\":\"POST JSON-RPC messages to this URL\"}; any other method (PUT, DELETE, PATCH, HEAD, OPTIONS) gets `new Response(null, {status:405, headers:{allow:'POST'}})` -- no body and no content-type header at all, not JSON. The content schema below applies only to the non-browser-GET case.","headers":{"Allow":{"schema":{"type":"string","enum":["POST"]}},"Gate-Version":{"$ref":"#/components/headers/GateVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[],"parameters":[{"$ref":"#/components/parameters/GateVersion"}]}},"/api/projects/{project_id}/approvals/phone":{"put":{"tags":["Actions, approvals and audit"],"operationId":"runsApproverSetPhone","summary":"Save or clear the approver's own mobile for phone approvals","description":"Approver key (gp_...) only. When a call is held, Gate phones each approver who saved a mobile (up to 3) through Odile's phone service: an opt-in call first (press 1 to allow), then the question, press 1 to approve or 2 to reject that exact call. Calls go only to US and Canadian numbers, 8:00-21:00 in the number's own time zone; the number is stored encrypted. phone: null stops calls. 404 when phone approvals are not available on this deployment.","security":[{"approverKey":[]},{"memberKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/GateVersion"}],"responses":{"200":{"description":"Saved or cleared.","content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":["string","null"]},"ends_in":{"type":["string","null"]},"note":{"type":"string"}}}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Not a US or Canadian number in E.164. Also returned before execution for unsupported Gate-Version, with supported_versions: [\"1\"].","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/UnsupportedGateVersion"}]}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"401":{"description":"No accepted approver key (gp_...) and no accepted, unrevoked member key, with authorization: Bearer <key>.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"403":{"description":"A member key cannot save a phone; use an approver key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"404":{"description":"Phone approvals are not available, or project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":["string","null"],"pattern":"^\\+1[2-9]\\d{2}[2-9]\\d{6}$"}}}}}},"x-gate-member-roles":["approver"]}},"/api/onboarding":{"get":{"operationId":"getOnboarding","tags":["Public and account"],"security":[],"summary":"Self-serve Free project and Demo Desk facts","description":"No account or payment required. Read-only facts about the existing project creation operation, key return and internal per-project Demo Desk. No resource is created by this GET; it has no Gate rate limiter.","responses":{"200":{"description":"Published onboarding facts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Onboarding"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}},"400":{"description":"Unsupported Gate-Version; supported_versions lists accepted values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedGateVersion"}}},"headers":{"Gate-Version":{"$ref":"#/components/headers/GateVersion"}}}},"parameters":[{"$ref":"#/components/parameters/GateVersion"}]}}},"components":{"securitySchemes":{"adminKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Project owner key (ga_...): full project administration, billing, members, key rotation and audit. Cannot approve, reject or reopen held actions; those require a separate approver. Existing admin endpoints also accept gm_ member keys only where their role allows. Send the complete value Bearer <key>, not the bare key.","x-permissions":["project:admin","billing:manage","members:manage","keys:rotate","audit:read"],"x-gate-permissions":["project:admin","billing:manage","members:manage","keys:rotate","audit:read"]},"approverKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Dedicated approver key (gp_...): reads project summary and held actions through /approvals, and approves, rejects or reopens them. Cannot manage apps, billing or members. All member roles can read this surface with gm_ keys; only the approver role can decide. Send the complete value Bearer <key>, not the bare key.","x-permissions":["approval-project:read","actions:read","approvals:decide"],"x-gate-permissions":["approval-project:read","actions:read","approvals:decide"]},"appKey":{"type":"apiKey","in":"header","name":"Authorization","description":"App key: gateway access only to this app's allowed method/path rules, subject to rate limits, expiry, call allowances, user-token rules and approval/run requirements. Cannot use project admin endpoints. Send the complete value Bearer <key>, not the bare key.","x-permissions":["gateway:allowed-routes","own-actions:read"],"x-gate-permissions":["gateway:allowed-routes","own-actions:read"]},"runToken":{"type":"apiKey","in":"header","name":"x-odile-run","description":"Run token in x-odile-run, always paired with its app key: narrows that app to the granted actions, scope, expiry, calls and approvals. Cannot expand app permissions or approve held actions.","x-permissions":["run:granted-actions","run:read","run:delegate-subset","run:recover","own-actions:read"],"x-gate-permissions":["run:granted-actions","run:read","run:delegate-subset","run:recover","own-actions:read"]},"memberKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Accepted team member key (gm_...): viewer reads non-owner-only admin routes; approver also decides held actions; admin also changes non-owner-only configuration but cannot decide held actions. No member can manage members, billing, packs, owner email or rotate the owner key. Send the complete value Bearer <key>, not the bare key.","x-permissions":{"viewer":["project:read","apps:read","runs:read","audit:read","actions:read"],"approver":["project:read","apps:read","runs:read","audit:read","actions:read","approvals:decide"],"admin":["project:read","apps:read","runs:read","audit:read","actions:read","project:configure","apps:manage","runs:manage"]},"x-gate-roles":{"viewer":["project:read","apps:read","runs:read","audit:read","actions:read"],"approver":["project:read","apps:read","runs:read","audit:read","actions:read","approvals:decide"],"admin":["project:read","apps:read","runs:read","audit:read","actions:read","project:configure","apps:manage","runs:manage"]}}},"parameters":{"ProjectId":{"name":"project_id","in":"path","required":true,"description":"Project id, p followed by 24 hex characters.","schema":{"type":"string","pattern":"^p[0-9a-f]{24}$"}},"AppId":{"name":"app_id","in":"path","required":true,"description":"App id, app_ followed by hex characters.","schema":{"type":"string"}},"GateVersion":{"name":"Gate-Version","in":"header","required":false,"description":"Optional compatibility selector. Omit or send 1 for current behavior. Any other value returns 400 with supported_versions before execution. Not forwarded upstream.","schema":{"type":"string","enum":["1"],"default":"1"}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"A plain sentence saying what went wrong and what to do."}},"additionalProperties":true},"PubCreateProjectRequest":{"type":"object","required":["name","upstream"],"additionalProperties":true,"properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"Shown in the dashboard and audit log. No control characters."},"upstream":{"type":"string","maxLength":2048,"format":"uri","description":"https:// base URL of the API to put Gate in front of; public DNS host only, no IP literal, no query/fragment/userinfo, port 443 or 8443 only."},"header_name":{"type":"string","maxLength":64,"description":"Optional upstream secret header name (default Authorization if header_value is set). Reserved and x-gate-/cf-/x-forwarded- names are refused."},"header_value":{"type":"string","maxLength":4096,"description":"Optional upstream secret header value, one line. Required if header_name is given. Stored sealed (AES-GCM), never returned."}}},"PubCreateProjectResponse":{"type":"object","required":["project_id","admin_key","gateway","dashboard","note"],"properties":{"project_id":{"type":"string","pattern":"^p[0-9a-f]{24}$"},"admin_key":{"type":"string","pattern":"^ga_p[0-9a-f]{24}_[A-Za-z0-9_-]+$","description":"Shown exactly once. Gate stores only its SHA-256 hash."},"gateway":{"type":"string","format":"uri","description":"Base URL apps call: {origin}/g/{project_id}."},"dashboard":{"type":"string","format":"uri"},"note":{"type":"string"},"owner_email_note":{"type":"string","description":"Present only when the deploy's OWNER_EMAIL flag is \"1\" (currently \"0\", so this field is absent today)."}}},"PubDeclarativeConfigBody":{"type":"object","additionalProperties":true,"properties":{"config":{"type":"string","description":"The odile.yaml file as YAML or JSON text."}},"description":"If the JSON body has no top-level 'config' key, the whole body is treated as the config object itself."},"PubDeclarativeSyncBody":{"allOf":[{"$ref":"#/components/schemas/PubDeclarativeConfigBody"}],"type":"object","properties":{"project_id":{"type":"string","description":"Existing project to sync; omit to create one from gateway.project."},"dry_run":{"type":"boolean"}}},"PubDeclarativeValidateOk":{"type":"object","required":["valid","warnings","config"],"properties":{"valid":{"type":"boolean","enum":[true]},"warnings":{"type":"array","items":{"type":"string"}},"config":{"type":"object","description":"Normalized config tree."}}},"PubDeclarativeValidateBad":{"type":"object","required":["valid","errors","warnings"],"properties":{"valid":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"string"},"description":"Each error is prefixed with its path, e.g. gateway.apps[0].routes[1]: ..."},"warnings":{"type":"array","items":{"type":"string"}}}},"PubDeclarativeSyncResult":{"type":"object","properties":{"ok":{"type":"boolean"},"project_id":{"type":["string","null"]},"dry_run":{"type":"boolean"},"steps":{"type":"array","items":{"type":"object","properties":{"do":{"type":"string"},"done":{"type":"boolean"}}}},"created":{"type":"object","properties":{"project":{"type":"object"},"apps":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"app_id":{"type":"string"},"key":{"type":"string"}}}},"approvers":{"type":"array","items":{"type":"object"}}}},"drift":{"type":"array","items":{"type":"object"},"description":"Existing apps/settings that differ from the file and were left unchanged."},"plugins":{"type":"array","items":{"type":"object"}},"warnings":{"type":"array","items":{"type":"string"}},"error":{"type":"string","description":"Present only on a non-ok response."},"errors":{"type":"array","items":{"type":"string"},"description":"Present only when the config itself failed validation (400)."}}},"PubMcpRequest":{"description":"A single JSON-RPC 2.0 message. Legacy requests also allow batch arrays; modern requests require protocolVersion/clientCapabilities metadata and matching standard headers.","oneOf":[{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{},"method":{"type":"string","enum":["server/discover","initialize","ping","tools/list","tools/call"]},"params":{"type":"object"}}},{"type":"array","items":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{},"method":{"type":"string"},"params":{"type":"object"}}}}]},"PubMcpResponse":{"description":"A single JSON-RPC response. Legacy batches return arrays. Modern results include resultType:complete and serverInfo metadata; discovery and tools/list also include ttlMs and cacheScope.","oneOf":[{"type":"object","required":["jsonrpc"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{},"result":{"type":"object"},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}},{"type":"array","items":{"type":"object"}}]},"PubMcpJsonRpcError":{"type":"object","required":["jsonrpc","error"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"anyOf":[{},{"type":"null"}]},"error":{"type":"object","properties":{"code":{"type":"integer","description":"-32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params/unknown tool; modern -32020 HeaderMismatch and -32022 Unsupported protocol version."},"message":{"type":"string"},"data":{"type":"object","description":"For -32022: supported protocol versions and the requested version.","properties":{"supported":{"type":"array","items":{"type":"string"}},"requested":{"type":"string"}}}}}}},"PubBearerPackVoucher":{"type":"object","required":["voucher","id","sku","calls","redeem","status"],"properties":{"voucher":{"type":"string","pattern":"^gpk_","description":"Shown exactly once."},"id":{"type":"string","pattern":"^[0-9a-f]{16}$"},"sku":{"type":"string","enum":["calls_100k"]},"calls":{"type":"integer","enum":[100000]},"state":{"type":"string","enum":["unspent","spent"],"description":"Present instead of voucher/redeem/status when the same settled payment was already used."},"redeem":{"type":"string"},"status":{"type":"string"}}},"PubBearerPackStatus":{"type":"object","required":["id","sku","calls","state","issued_at"],"properties":{"id":{"type":"string","pattern":"^[0-9a-f]{16}$"},"sku":{"type":"string","enum":["calls_100k"]},"calls":{"type":"integer"},"state":{"type":"string","enum":["unspent","spent"]},"issued_at":{"type":"integer","description":"Epoch milliseconds."},"spent_at":{"type":"integer","description":"Epoch milliseconds; present only once the voucher has been redeemed."}}},"PubBearerPackChallenge":{"type":"object","required":["x402Version","resource","accepts","error"],"properties":{"x402Version":{"type":"integer","enum":[2]},"resource":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","items":{"type":"object"},"description":"Exact-scheme USDC-on-Base payment requirements, including maxAmountRequired."},"extensions":{"type":"object","properties":{"bazaar":{"type":"object"}}},"error":{"type":"string"}}},"PubAiCatalog":{"type":"object","required":["specVersion","entries"],"properties":{"specVersion":{"type":"string","enum":["1.0"]},"entries":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string"},"type":{"type":"string"},"url":{"type":"string"}}}},"paths":{"type":"object","description":"Present only when X402_PACKS is \"1\" (currently \"0\", so absent)."},"components":{"type":"object","description":"Present only alongside paths, same condition."}}},"PubOpenshellManifest":{"type":"object","required":["implementation","implementation_version","openshell_version","protocol_version","guide","hosting","setup","files"],"properties":{"implementation":{"type":"string","enum":["odile/gate"]},"implementation_version":{"type":"string"},"openshell_version":{"type":"string","enum":["0.1.5"]},"protocol_version":{"type":"string","enum":["1.0"]},"guide":{"type":"string"},"hosting":{"type":"string"},"setup":{"type":"string"},"files":{"type":"array","items":{"type":"object","required":["path","sha256","url"],"properties":{"path":{"type":"string"},"sha256":{"type":"string"},"url":{"type":"string"}}}}}},"PubDemoJwks":{"type":"object","required":["keys"],"properties":{"keys":{"type":"array","items":{"type":"object","required":["kty","crv","x","kid","alg","use"],"properties":{"kty":{"type":"string","enum":["OKP"]},"crv":{"type":"string","enum":["Ed25519"]},"x":{"type":"string"},"kid":{"type":"string","enum":["demo-1"]},"alg":{"type":"string","enum":["EdDSA"]},"use":{"type":"string","enum":["sig"]}}}}}},"PubDemoTokenResponse":{"type":"object","required":["token","user","header","expires_in","user_tokens","note"],"properties":{"token":{"type":"string","description":"EdDSA JWT."},"user":{"type":"string"},"header":{"type":"string","enum":["x-odile-user-token"]},"expires_in":{"type":"integer","enum":[600]},"user_tokens":{"type":"object","properties":{"jwks_url":{"type":"string"},"issuer":{"type":"string"},"audience":{"type":"string"}}},"note":{"type":"string"}}},"PubProofStats":{"type":"object","required":["scope","month","calls_this_month","active_apps","stopped_this_month","held_for_approval_this_month","loops_stopped_last_30d","updated_at"],"properties":{"scope":{"type":"string","enum":["Odile Labs' own AI agents"]},"month":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"calls_this_month":{"type":"integer"},"active_apps":{"type":"integer"},"stopped_this_month":{"type":"integer"},"held_for_approval_this_month":{"type":"integer"},"loops_stopped_last_30d":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"ProjMember":{"type":"object","properties":{"id":{"type":"string","example":"mem_0123456789abcdef"},"name":{"type":"string"},"role":{"type":"string","enum":["viewer","approver","admin"]},"state":{"type":"string","enum":["invited","active","revoked"]},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":["string","null"],"format":"date-time"}},"required":["id","name","role","state","created_at","last_used_at"]},"ProjInviteMemberRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"description":"No control characters."},"role":{"type":"string","enum":["viewer","approver","admin"]}},"required":["name","role"]},"ProjInviteMemberResponse":{"type":"object","properties":{"member":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"role":{"type":"string","enum":["viewer","approver","admin"]},"state":{"type":"string","enum":["invited"]},"created_at":{"type":"string","format":"date-time"},"invite_expires_at":{"type":"string","format":"date-time"}},"required":["id","name","role","state","created_at","invite_expires_at"]},"invite_url":{"type":"string","description":"One-time invite link; share it yourself, Gate sends no email. Valid 72 hours. Opening it does not consume it; accepting it does."}},"required":["member","invite_url"]},"ProjRiskModel":{"oneOf":[{"type":"null","description":"Removes the installed model."},{"type":"object","description":"A version-1 risk tree ensemble, at most 512 KiB.","properties":{"version":{"type":"integer","enum":[1]},"project_id":{"type":"string","description":"Must equal this project's id."},"feature_names":{"type":"array","items":{"type":"string"},"description":"Must exactly equal ['method','req_bytes','anomaly_score','refused_ratio_60m','run_held_count','prior_approved','prior_rejected']."},"base_margin":{"type":"number"},"trees":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/ProjRiskTreeNode"}}},"required":["version","project_id","feature_names","base_margin","trees"],"additionalProperties":false}]},"ProjRiskTreeNode":{"description":"A leaf or a split node; splits may nest to a maximum depth of 4.","oneOf":[{"type":"object","properties":{"leaf":{"type":"number"}},"required":["leaf"],"additionalProperties":false},{"type":"object","properties":{"feature":{"type":"string","enum":["method","req_bytes","anomaly_score","refused_ratio_60m","run_held_count","prior_approved","prior_rejected"]},"threshold":{"type":"number"},"value":{"type":"number"},"missing_left":{"type":"boolean"},"left":{"$ref":"#/components/schemas/ProjRiskTreeNode"},"right":{"$ref":"#/components/schemas/ProjRiskTreeNode"}},"required":["feature","threshold","value","missing_left","left","right"],"additionalProperties":false}]},"ProjSetSecretRequest":{"type":"object","properties":{"header_name":{"type":["string","null"],"description":"Defaults to Authorization. Not a reserved header name and not starting with cf-, x-forwarded- or x-gate-."},"header_value":{"type":["string","null"],"maxLength":4096,"description":"One line, up to 4,096 characters. null removes the secret."}},"required":["header_value"]},"ProjExtraSettings":{"type":"object","properties":{"extra_calls":{"type":"string","enum":["on","off"]},"price":{"type":"string"},"max_extra_millions":{"type":"integer"},"month":{"type":"string","example":"2026-11"},"extra_used":{"type":"integer"},"billed":{"type":"integer"},"why":{"type":"string","description":"Present only when extra_calls is off."}},"required":["extra_calls","price","max_extra_millions","month","extra_used","billed"]},"ProjPack":{"type":"object","properties":{"id":{"type":"string"},"sku":{"type":"string","enum":["calls_100k"]},"calls":{"type":"integer"},"remaining":{"type":"integer"},"paid_amount":{"type":"string"},"network":{"type":"string"},"payer":{"type":"string"},"settlement_id":{"type":"string"},"created_at":{"type":"integer"}},"required":["id","sku","calls","remaining","paid_amount","network","payer","settlement_id","created_at"]},"ProjPacksResponse":{"type":"object","properties":{"packs":{"type":"array","items":{"$ref":"#/components/schemas/ProjPack"}},"remaining_calls":{"type":"integer"},"allowance":{"type":"object","properties":{"month":{"type":"string"},"used":{"type":"integer"},"included":{"type":"integer"},"remaining":{"type":"integer"},"resets_on":{"type":"string"}}}},"required":["packs","remaining_calls","allowance"]},"ProjAlertSettings":{"type":"object","properties":{"webhook_url":{"type":["string","null"],"description":"Origin only, e.g. https://hooks.example.com/…"},"threshold":{"type":"integer"},"idle_days":{"type":"integer"},"last_alert_at":{"type":["string","null"],"format":"date-time"},"recent":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"at":{"type":"integer"},"app_id":{"type":"string"},"app_name":{"type":"string"},"refused_count":{"type":"integer"},"top_status":{"type":"integer"},"top_route":{"type":["string","null"]},"delivered":{"type":"boolean"},"http_status":{"type":["integer","null"]}}}}},"required":["webhook_url","threshold","idle_days","last_alert_at","recent"]},"ProjSetAlertsRequest":{"type":"object","properties":{"webhook_url":{"type":["string","null"]},"threshold":{"type":"integer","minimum":5,"maximum":1000},"idle_days":{"type":"integer","minimum":1,"maximum":90}}},"ProjAlertEmailSettings":{"type":"object","properties":{"alert_email":{"type":["string","null"],"format":"email"},"note":{"type":"string"}},"required":["alert_email","note"]},"ProjEnterpriseSettings":{"type":"object","properties":{"signed_webhooks":{"type":"boolean"},"ip_allowlist":{"type":"array","items":{"type":"string"}},"observe_only":{"type":"boolean"},"siem":{"type":["object","null"],"properties":{"url":{"type":"string","description":"Origin only."},"format":{"type":"string","enum":["json","splunk_hec"]},"header_name":{"type":["string","null"]}}},"siem_delivery":{"type":["object","null"],"description":"Audit events wait in a durable outbox until the SIEM answers 2xx (at-least-once). Each delivered event carries seq and event_id (project id + seq); seq never repeats, so a jump means dropped events.","properties":{"last_status":{"type":["integer","null"]},"last_ok_at":{"type":"integer"},"last_error_at":{"type":"integer"},"failures":{"type":"integer"},"retry_at":{"type":["integer","null"],"description":"During an outage: when the next delivery attempt is due (ms since epoch)."},"pending":{"type":"integer","description":"Events not yet accepted by the SIEM."},"oldest_seq":{"type":["integer","null"]},"acked_seq":{"type":"integer","description":"The last seq the SIEM accepted."},"dropped":{"type":"integer","description":"Events discarded because more than 100,000 were waiting; also announced as gate.siem_overflow."}}},"store_audit":{"type":"boolean"},"user_tokens":{"type":["object","null"],"properties":{"jwks_url":{"type":"string"},"issuer":{"type":"string"},"audience":{"type":"string"},"claim":{"type":"string"}}},"block_rules":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"pattern":{"type":"string"},"flags":{"type":"string"}}}},"signing_secret":{"type":"string","description":"Present only in the response to a call with rotate_signing_secret: true; shown once."},"note":{"type":"string","description":"Present only alongside signing_secret."}},"required":["signed_webhooks","ip_allowlist","observe_only","siem","siem_delivery","store_audit","user_tokens","block_rules"]},"ProjSetEnterpriseRequest":{"type":"object","properties":{"ip_allowlist":{"type":"array","maxItems":50,"items":{"type":"string"}},"observe_only":{"type":"boolean"},"siem":{"type":["object","null"],"properties":{"url":{"type":"string"},"format":{"type":"string","enum":["json","splunk_hec"]},"header_name":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$"},"header_value":{"type":"string","maxLength":500}}},"store_audit":{"type":"boolean"},"block_rules":{"oneOf":[{"type":"string","enum":["basic"]},{"type":"array","maxItems":20,"items":{"type":"object","properties":{"label":{"type":"string","maxLength":60},"pattern":{"type":"string","maxLength":200},"flags":{"type":"string","enum":["","i"]}},"required":["label","pattern"]}}]},"user_tokens":{"type":["object","null"],"properties":{"jwks_url":{"type":"string"},"issuer":{"type":"string","maxLength":300},"audience":{"type":"string","maxLength":300},"claim":{"type":"string","maxLength":300}},"required":["jwks_url","issuer"]},"rotate_signing_secret":{"type":"boolean"}},"additionalProperties":false},"ProjSetupCheck":{"type":"object","properties":{"format_version":{"type":"integer"},"checked_at":{"type":"string","format":"date-time"},"project_id":{"type":"string"},"verification":{"type":"string","enum":["configuration_only"]},"status":{"type":"string","enum":["configured","review","action_required"]},"summary":{"type":"object","properties":{"apps_checked":{"type":"integer"},"errors":{"type":"integer"},"warnings":{"type":"integer"}}},"observed":{"type":"object","properties":{"observe_only":{"type":"boolean"},"user_tokens_configured":{"type":"boolean"},"active_approvers":{"type":"integer"},"approval_runs":{"type":"integer"},"apps":{"type":"array","items":{"type":"object"}}}},"findings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"level":{"type":"string","enum":["error","warning"]},"app_id":{"type":["string","null"]},"title":{"type":"string"},"detail":{"type":"string"},"remediation":{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"},"body":{"type":"object"},"requires_input":{"type":"boolean"},"note":{"type":"string"}}}}}}},"required":["format_version","checked_at","project_id","verification","status","summary","observed","findings"]},"ProjMetrics":{"type":"object","properties":{"plan":{"type":"string"},"pack_calls_remaining":{"type":"integer"},"window":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"audit":{"type":"object","properties":{"calls":{"type":"integer"},"by_status":{"type":"object","additionalProperties":{"type":"integer"}},"by_reason":{"type":"object","additionalProperties":{"type":"integer"}},"duration_ms":{"type":"object","properties":{"average":{"type":["number","null"]},"max":{"type":["integer","null"]}}}}},"usage":{"type":"object","properties":{"month":{"type":"string"},"calls":{"type":"integer"},"included_calls":{"type":"integer"},"resets_on":{"type":"string"}}},"anomaly":{"type":"object"},"idle":{"type":"object","properties":{"days":{"type":"integer"},"apps":{"type":"array","items":{"type":"object","properties":{"app_id":{"type":"string"},"app_name":{"type":"string"},"idle_since":{"type":"string","format":"date-time"},"last_call_at":{"type":["string","null"],"format":"date-time"}}}}}},"coverage":{"type":"object","properties":{"local_audit_enabled":{"type":"boolean"},"observe_only":{"type":"boolean"},"complete":{"type":"boolean","enum":[false]},"notes":{"type":"array","items":{"type":"string"}}}}},"required":["plan","window","audit","usage","anomaly","idle","coverage"]},"ProjChangesResponse":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"at":{"type":"integer"},"action":{"type":"string"},"target":{"type":["string","null"]},"status":{"type":"integer"},"ip":{"type":["string","null"]},"user_agent":{"type":["string","null"]},"before":{"type":["string","null"]},"after":{"type":["string","null"]},"actor_id":{"type":["string","null"]},"actor_name":{"type":["string","null"]}}}}},"required":["rows"]},"ProjPilotReport":{"type":"object","properties":{"days":{"type":"integer"},"calls":{"type":"integer"},"by_outcome":{"type":"object","additionalProperties":{"type":"integer"}},"loops":{"type":"array","items":{"type":"object","properties":{"app":{"type":"string"},"route":{"type":"string"},"calls":{"type":"integer"},"mode":{"type":"string","enum":["stopped","would have stopped"]}}}}},"required":["days","calls","by_outcome","loops"]},"ProjSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"upstream":{"type":"string"},"header_name":{"type":["string","null"]},"has_secret":{"type":"boolean"},"plan":{"type":"string","enum":["free","pro","internal"]},"limits":{"type":"object","properties":{"apps":{"type":"integer"},"calls_per_month":{"type":"integer"},"retention_days":{"type":"integer"}}},"usage":{"type":"object","properties":{"month":{"type":"string"},"calls":{"type":"integer"},"apps":{"type":"integer"},"resets_on":{"type":"string"},"used":{"type":"integer"},"allowed":{"type":"integer"},"upgrade":{"type":"string"},"checkout":{"type":"string"}}},"extra":{"$ref":"#/components/schemas/ProjExtraSettings"},"x402_packs":{"type":"boolean"},"pack_calls_remaining":{"type":"integer"},"unauthenticated":{"type":"object","properties":{"this_hour":{"type":"integer"},"last_24h":{"type":"integer"},"logged_per_hour":{"type":"integer"}}},"loops":{"type":"object"},"member":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"role":{"type":"string","enum":["viewer","approver","admin"]}}}},"required":["id","name","upstream","header_name","has_secret","plan","limits","usage","extra","unauthenticated","loops"]},"AppsResponseAllow":{"oneOf":[{"type":"null","description":"No filtering: full upstream response passes through."},{"type":"array","minItems":1,"maxItems":32,"items":{"type":"string","maxLength":256,"pattern":"^/"},"description":"JSON Pointer-style paths (up to 16 /-separated segments each); * matches one segment of any name; selecting a container keeps its whole subtree."},{"type":"null"}]},"AppsModels":{"oneOf":[{"type":"null","description":"No model restriction."},{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","minLength":1,"maxLength":101,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,99}\\*?$"},"description":"Exact model names, or a prefix ending in '*'. Duplicates are silently removed."},{"type":"null"}]},"AppsLoopStatus":{"type":"object","required":["app_id","repeats","window_seconds","effective"],"properties":{"sweep":{"type":"object","description":"Saved route-sweep rule.","required":["calls","window_seconds","mode"],"properties":{"calls":{"type":"integer"},"window_seconds":{"type":"integer"},"mode":{"type":"string","enum":["alert","block","off"]}}},"app_id":{"type":"string"},"repeats":{"type":"integer","minimum":3,"maximum":100,"description":"Saved setting."},"window_seconds":{"type":"integer","minimum":1,"maximum":60,"description":"Saved setting."},"effective":{"type":"object","required":["repeats","window_seconds"],"description":"What the gateway enforces right now (tightened while the anomaly guard holds this app in a strict window).","properties":{"repeats":{"type":"integer"},"window_seconds":{"type":"number"}}}}},"AppsLoopUpdateRequest":{"type":"object","properties":{"repeats":{"type":"integer","minimum":3,"maximum":100,"description":"Identical-call count that trips the breaker. Omit to keep the current value."},"window_seconds":{"type":"integer","minimum":1,"maximum":60,"description":"Window the repeats must fall inside. Omit to keep the current value."},"sweep":{"type":"object","additionalProperties":false,"description":"Route sweep: calls to one route rule with any ids, pages or bodies. At calls inside window_seconds Gate sends one gate.route_sweep webhook and writes an audit row; mode block also refuses further calls to that route (429, x-gate-refused: route_sweep) until the window ends; off turns it off. Omitted fields keep their current values (defaults: 100 calls, 600 s; mode block for apps created through POST /apps, alert for older apps without a saved mode and for Machine Access connection apps).","properties":{"calls":{"type":"integer","minimum":10,"maximum":100000},"window_seconds":{"type":"integer","minimum":10,"maximum":3600},"mode":{"type":"string","enum":["alert","block","off"]}}}}},"AppsAnomalyStatus":{"type":"object","required":["app_id","mode","z_threshold","min_minutes","half_life"],"properties":{"app_id":{"type":"string"},"mode":{"type":"string","enum":["off","alert","strict"],"default":"alert"},"z_threshold":{"type":"number","minimum":2,"maximum":10,"default":4},"min_minutes":{"type":"integer","minimum":1,"maximum":30,"default":3,"description":"Consecutive anomalous minutes required before the guard fires."},"half_life":{"type":"integer","minimum":5,"maximum":1440,"default":60,"description":"Baseline decay half-life, in minutes."},"strict_until":{"type":["integer","null"],"description":"Epoch ms after which the guard-opened strict window ends; present only while that window is still in the future (anomalyConfig returns a raw timestamp, not an ISO string)."}}},"AppsAnomalyUpdateRequest":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["off","alert","strict"]},"z_threshold":{"type":"number","minimum":2,"maximum":10},"min_minutes":{"type":"integer","minimum":1,"maximum":30},"half_life":{"type":"integer","minimum":5,"maximum":1440}},"description":"All fields optional (each keeps its current value if omitted), but an unknown key is a 400."},"AppsSigningStatus":{"type":"object","required":["app_id","enabled","key","retiring"],"properties":{"app_id":{"type":"string"},"enabled":{"type":"boolean"},"key":{"type":["object","null"],"properties":{"kid":{"type":"string"},"created_at":{"type":"integer","description":"Epoch ms."}}},"retiring":{"type":"array","items":{"type":"object","properties":{"kid":{"type":"string"},"created_at":{"type":"integer"},"retire_at":{"type":"integer","description":"Epoch ms after which this key is no longer honored."}}}}}},"AppsLearning":{"type":"object","required":["active","started_at","ends_at","delete_at","routes","templates","per_minute"],"properties":{"active":{"type":"boolean"},"started_at":{"type":["string","null"],"format":"date-time"},"ends_at":{"type":["string","null"],"format":"date-time"},"delete_at":{"type":["string","null"],"format":"date-time","description":"When the collected templates are purged (7 days after ends_at)."},"routes":{"type":"array","items":{"type":"string"},"description":"Suggested route rules, e.g. GET /orders/:id."},"templates":{"type":"array","items":{"type":"object","required":["rule","calls"],"properties":{"rule":{"type":"string"},"calls":{"type":"integer"}}}},"per_minute":{"type":"integer","minimum":10,"maximum":6000,"description":"2x the p99 of observed per-minute call counts, clamped to 10-6000."}}},"AppsApp":{"type":"object","required":["id","name","per_minute","created_at","revoked_at","last_call_at","expires_at","max_calls","calls_used","idle_since","routes","key","models","loop","anomaly","suspended","response"],"properties":{"id":{"type":"string","pattern":"^app_[0-9a-f]{16}$"},"name":{"type":"string","maxLength":80},"per_minute":{"type":"integer","minimum":1,"maximum":6000},"created_at":{"type":"integer","description":"Epoch ms."},"revoked_at":{"type":["integer","null"],"description":"Epoch ms, or null if still active."},"last_call_at":{"type":["integer","null"],"description":"Epoch ms of the app's last allowed call, or null."},"template":{"type":"string","enum":["stripe","github","shopify","hubspot","supabase","slack","recall","quickbooks","xero"],"description":"Present only when the app was created from a built-in template."},"approval_routes":{"type":"array","items":{"type":"string"},"description":"Present only with template: that template's rules which are normally held for approval."},"refused_routes":{"type":"array","items":{"type":"string"},"description":"Present only with template: that template's rules which are normally refused outright."},"expires_at":{"type":["string","null"],"format":"date-time","description":"Client-handoff key expiry (Pro/internal only)."},"max_calls":{"type":["integer","null"],"description":"Client-handoff call cap (Pro/internal only)."},"calls_used":{"type":"integer","description":"Calls counted against max_calls so far; 0 if no limit was ever set."},"idle_since":{"type":["string","null"],"format":"date-time"},"routes":{"type":"array","items":{"type":"string"},"description":"The app's allow-list, as METHOD /path strings."},"key":{"type":["string","null"],"description":"Masked, e.g. gk_<id>_...; null if the app has no active key."},"models":{"oneOf":[{"type":"null","description":"No model restriction."},{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","minLength":1,"maxLength":101,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,99}\\*?$"},"description":"Exact model names, or a prefix ending in '*'. Duplicates are silently removed."},{"type":"null"}]},"loop":{"type":"object","required":["repeats","window_seconds"],"properties":{"repeats":{"type":"integer"},"window_seconds":{"type":"number"}}},"anomaly":{"$ref":"#/components/schemas/AppsAnomalyStatus"},"suspended":{"type":"boolean"},"response":{"type":"object","required":["allow"],"properties":{"allow":{"oneOf":[{"type":"null","description":"No filtering: full upstream response passes through."},{"type":"array","minItems":1,"maxItems":32,"items":{"type":"string","maxLength":256,"pattern":"^/"},"description":"JSON Pointer-style paths (up to 16 /-separated segments each); * matches one segment of any name; selecting a container keeps its whole subtree."},{"type":"null"}]}}}}},"AppsCreateAppRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"No control characters."},"template":{"type":"string","enum":["stripe","github","shopify","hubspot","supabase","slack","recall","quickbooks","xero"]},"routes":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"},"description":"Rule strings like \"GET /orders/:id\" or \"POST /tickets\"; see the operation description for the full grammar. Required unless template is given without this field."},"per_minute":{"type":"integer","minimum":1,"maximum":6000,"default":60},"expires_at":{"type":"string","format":"date-time","description":"Future, timezone-qualified, at most 30 days out. Requires Pro/internal plan."},"max_calls":{"type":"integer","minimum":1,"maximum":100000,"description":"Requires Pro/internal plan."},"models":{"oneOf":[{"type":"null","description":"No model restriction."},{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","minLength":1,"maxLength":101,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,99}\\*?$"},"description":"Exact model names, or a prefix ending in '*'. Duplicates are silently removed."},{"type":"null"}]},"runs":{"type":"string","enum":["off","writes","all"],"default":"writes","description":"Whether the app's calls need a Gate Actions run (x-odile-run). Default writes since 17 Nov 2026: every write needs a run, reads go straight through. A template app defaults to off, because its writes are already held for approval. Use off for a model or MCP gateway, where every call is a POST, or for an app that writes directly; all puts reads inside runs too."}}},"RunsActionSpec":{"description":"One action this run (or, for an object item, this scoped item) may call through the gateway. A plain string is shorthand for {rule: that string}.","oneOf":[{"type":"string","description":"Shorthand for {rule: <this string>}, e.g. \"PATCH /tickets/:id\" or \"GET /orders/{customer}/*\".","example":"PATCH /tickets/:id"},{"type":"object","required":["rule"],"properties":{"rule":{"type":"string","description":"\"METHOD /path\" (bindAction/parseRule). {name} placeholders other than {user} must all be keys of the run's scope; {user} is left for per-user rules. Must parse as a valid route rule after binding or the whole run is refused.","example":"PATCH /tickets/:id"},"max":{"type":["integer","null"],"minimum":1,"maximum":100000,"description":"Calls this action may make inside the run's lifetime; null (default) means unlimited (bounded only by the run's own max_calls, if any)."},"approval":{"type":"boolean","default":false,"description":"true holds every matching call for a human approver (or approver-role member) before it runs. A check/idempotent recovery setting cannot be combined with approval:true."},"check":{"type":["string","null"],"maxLength":300,"description":"A literal GET recovery lookup for a write action without approval, e.g. \"GET /bookings?idempotency_key={key}\": exactly one {key} placeholder, every other {name} bound from scope, no further path parameters. Only legal when the action's method is a write (not GET/HEAD/OPTIONS) and approval is not true."},"idempotent":{"type":"boolean","description":"Admin's attestation that the upstream API itself dedupes on the Idempotency-Key header, so a retry after an unknown outcome never double-runs. Only legal together with check."}}}]},"RunsActionGrant":{"type":"object","description":"One action as granted on a live run (echoed back in describe-run shapes).","properties":{"rule":{"type":"string","description":"\"METHOD /path\" after scope binding."},"approval_required":{"type":"boolean"},"calls_left":{"type":["integer","null"],"description":"null means unlimited for this action."},"recoverable":{"type":"boolean","description":"Present (true) only when the action carries a check recovery path."}}},"RunsRun":{"type":"object","description":"What a run allows right now (describeRun). Returned by run creation, delegation, GET /_gate/run and every runs listing/detail route.","properties":{"run_id":{"type":"string","example":"0123456789abcdef"},"app_id":{"type":"string"},"label":{"type":["string","null"],"maxLength":120},"scope":{"type":"object","additionalProperties":{"type":"string"},"description":"The literal values bound into every {name} placeholder in this run's actions; up to 10 names, each 1-200 chars of letters/digits/._~-."},"parent_run_id":{"type":["string","null"],"description":"Set when this run was created by delegation from another run (out of this fragment's scope: POST /g/.../_gate/run/delegate)."},"depth":{"type":"integer","description":"0 for a top-level run; a delegation chain is refused past depth 5."},"expires_at":{"type":"string","format":"date-time"},"seconds_left":{"type":"integer","minimum":0},"calls_left":{"type":["integer","null"],"description":"null means the run has no max_calls cap."},"actions":{"type":"array","items":{"$ref":"#/components/schemas/RunsActionGrant"}},"writes_need":{"type":"string","description":"Fixed hint text (the same for every run) for calls made inside a run: the Idempotency-Key, x-odile-action and /_gate/recover protocol. Gate dedupes Idempotency-Key only inside runs; outside a run it forwards the header to the upstream untouched."}}},"RunsRunListItem":{"allOf":[{"$ref":"#/components/schemas/RunsRun"}],"type":"object","description":"One row of GET /runs: a RunsRun plus its current lifecycle state and raw created_at.","properties":{"state":{"type":"string","enum":["active","revoked","expired","invalid"],"description":"invalid means the run row itself (or an ancestor) could not be resolved; revoked/expired follow from the run or any ancestor in its delegation chain."},"used":{"type":"integer","description":"Calls made against this run (incremented on every gateway call the run grants, whether or not the run has a max_calls cap)."},"created_at":{"type":"string","format":"date-time"}}},"RunsRunTreeItem":{"allOf":[{"$ref":"#/components/schemas/RunsRun"}],"type":"object","description":"One node of GET /runs/{run_id}/tree: the named run and every run delegated from it, down to 5 levels, each with its own live state.","properties":{"state":{"type":"string","enum":["active","revoked","expired","invalid"]}}},"RunsTimelineEvent":{"type":"object","description":"One audit row for this run (gateway calls, approval decisions, delegations), newest first on the page as returned, oldest-to-newest after the handler reverses it.","properties":{"id":{"type":"integer","description":"Audit row id; pass as ?before= to page further back."},"at":{"type":"integer","description":"Epoch milliseconds."},"event":{"type":["string","null"],"description":"e.g. call, recover, approval_approved, approval_rejected, approval_reopened, run_delegated."},"method":{"type":["string","null"]},"rule":{"type":["string","null"],"description":"The matched route rule (audit.route), or the path's first segment when none matched."},"status":{"type":"integer"},"reason":{"type":["string","null"]},"action_id":{"type":["string","null"]},"approver_name":{"type":["string","null"]},"decided_at":{"type":["integer","null"],"description":"Epoch milliseconds."},"child_run_id":{"type":["string","null"]},"actor_id":{"type":["string","null"],"description":"Member id, when a team member (not a bare key) performed the action."},"actor_name":{"type":["string","null"]}}},"RunsTimelineChild":{"type":"object","description":"A run delegated directly from this run.","properties":{"run_id":{"type":"string"},"parent_run_id":{"type":"string"},"app_id":{"type":"string"},"depth":{"type":"integer"},"at":{"type":"integer","description":"created_at, epoch milliseconds."},"state":{"type":"string","enum":["active","revoked","expired","invalid"]}}},"RunsRiskFeature":{"type":"object","description":"One of the up to two features that contributed most to this action's risk score.","properties":{"feature":{"type":"string","enum":["method","req_bytes","anomaly_score","refused_ratio_60m","run_held_count","prior_approved","prior_rejected"]},"value":{"type":["number","null"]},"contribution":{"type":"number"}}},"RunsAction":{"type":"object","description":"One held or decided action in the approval queue (listActions). path and body are decrypted on read (AES-GCM under the project key) and are cleared once an action is rejected; risk/risk_features are present only when the project has a risk model configured (PUT /admin/risk-model, out of this fragment's scope).","properties":{"action_id":{"type":"string","example":"act_0123456789abcdef"},"run_id":{"type":["string","null"],"description":"null when the call was made directly against an app key with no run token."},"app_id":{"type":"string"},"state":{"type":"string","enum":["pending","approved","rejected","expired","executing","unknown"]},"method":{"type":"string"},"path":{"type":["string","null"],"description":"Decrypted upstream path; null if decryption failed."},"body":{"type":["string","null"],"description":"Decrypted request body, truncated to 20000 bytes, or \"(<n> bytes, not text)\" for binary content."},"req_bytes":{"type":["integer","null"]},"req_sha256":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"decided_at":{"type":["string","null"],"format":"date-time"},"decided_by":{"type":["string","null"],"description":"\"member:<id>\", \"approver:<id>\" or \"admin\"."},"note":{"type":["string","null"],"maxLength":300},"outcome_status":{"type":["integer","null"]},"risk":{"type":"number","description":"0-1 risk score from the project's risk model; omitted when no model is set."},"risk_features":{"type":"array","items":{"$ref":"#/components/schemas/RunsRiskFeature"}}}},"RunsApprover":{"type":"object","properties":{"id":{"type":"string","example":"0123456789abcdef"},"name":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["active","revoked"]}}},"RunsAuditRow":{"type":"object","description":"One row of the project's call-and-decision audit log (no request/response bodies, raw paths or query strings are ever stored: only the matched route rule or first path segment, a SHA-256 of the raw path, and the request body's size/SHA-256).","properties":{"id":{"type":"integer"},"at":{"type":"integer","description":"Epoch milliseconds."},"app_id":{"type":["string","null"]},"app_name":{"type":["string","null"]},"method":{"type":"string"},"route":{"type":["string","null"]},"segment":{"type":["string","null"]},"path_sha256":{"type":"string"},"status":{"type":"integer"},"duration_ms":{"type":"integer"},"req_bytes":{"type":["integer","null"]},"req_sha256":{"type":["string","null"]},"reason":{"type":["string","null"]},"country":{"type":["string","null"]},"run_id":{"type":["string","null"]},"event":{"type":["string","null"]},"action_id":{"type":["string","null"]},"approver_name":{"type":["string","null"]},"decided_at":{"type":["integer","null"]},"child_run_id":{"type":["string","null"]},"actor_id":{"type":["string","null"]},"actor_name":{"type":["string","null"]},"signed":{"type":["integer","null"]},"sig_kid":{"type":["string","null"]}}},"RunsAuditProofRow":{"allOf":[{"$ref":"#/components/schemas/RunsAuditRow"}],"type":"object","properties":{"prev_chain":{"type":["string","null"]},"chain":{"type":["string","null"]}}},"RunsAuditProof":{"type":"object","description":"A signed (HMAC), hash-chained export of the audit log for independent tamper verification, plus a page of decided-action outcome labels for training a risk model. When the project's Enterprise config has store_audit=false, this route instead returns {enabled: false, note}.","properties":{"version":{"type":"integer","enum":[1]},"first_id":{"type":["integer","null"],"description":"null when the requested range starts before what is currently retained."},"last_id":{"type":"integer"},"project_id":{"type":"string"},"genesis":{"type":"object","properties":{"chain":{"type":"string"},"at":{"type":"integer"},"first_id":{"type":"integer"}}},"from":{"type":"integer"},"to":{"type":"integer"},"previous_chain":{"type":"string"},"head":{"type":"string"},"next_from":{"type":["integer","null"],"description":"Pass as ?from= to continue a truncated (>10,000 row) export."},"rows":{"type":"array","items":{"$ref":"#/components/schemas/RunsAuditProofRow"}},"actions_after":{"type":["string","null"]},"next_actions_after":{"type":["string","null"],"description":"Pass as ?actions_after= to continue a truncated action-label page."},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"app":{"type":"string"},"method":{"type":"string"},"route":{"type":["string","null"]},"req_bytes":{"type":["integer","null"]},"created_at":{"type":"integer"},"decided_at":{"type":["integer","null"]},"state":{"type":["string","null"]},"outcome_status":{"type":["integer","null"]},"features":{"type":["object","null"]}}}},"signature":{"type":"string","description":"Hex HMAC over the rest of this object (canonical JSON), keyed per project."}}},"RunsAuditVerifyResult":{"type":"object","description":"Result of re-checking a previously exported RunsAuditProof's hash chain and signature.","properties":{"intact":{"type":"boolean"},"rows":{"type":"integer","description":"Present when intact: true."},"head":{"type":"string","description":"Present when intact: true."},"broken_at":{"type":"integer","description":"1-based row index (or rows.length+1 for a head/tail mismatch) where the chain stopped matching; present for most intact: false reasons."},"row_id":{"type":["integer","null"]},"reason":{"type":"string","enum":["missing_row","chain_mismatch","head_mismatch","signature_unavailable","signature_mismatch"]}}},"GwRefusal":{"type":"string","description":"Every refusal reason this route can produce, as the x-gate-refused header value and/or the JSON error field (see each response's own description for which apply to it, and which of the two carry it).","enum":["project_not_found","bad_key","key_expired","call_limit_reached","app_suspended","ip_not_allowed","unsafe_path","policy_changed","bad_run","run_revoked","run_expired","action_not_in_run","run_required","user_tokens_off","bad_user_token","outside_user_scope","route_not_allowed","body_too_large","approval_body_too_large","blocked_by_rule","model_not_allowed","run_limit_reached","required_field_missing","bad_action","approval_pending","approval_rejected","approval_expired","already_executed","outcome_unknown","approval_mismatch","idempotency_key_required","rate_limited","loop_detected","monthly_quota","secret_unavailable","approval_unavailable","signing_key_missing","signing_key_unavailable","signing_failed","upstream_timeout","upstream_error","response_redaction_failed","method_not_allowed","no_such_operation","still_running","no_check","check_not_allowed","recover_conflict","aws_subscription_inactive"]},"GwApprovalHeld":{"type":"object","required":["outcome","action_id","expires_at","resume","job_id","status_url"],"properties":{"outcome":{"type":"string","const":"approval_required"},"action_id":{"type":"string","description":"act_ + 16 hex characters. Send it back as x-odile-action once approved."},"expires_at":{"type":"string","format":"date-time","description":"At most 24 h out, and never later than the run's own expiry."},"resume":{"type":"string","description":"Always: 'after approval, send the identical request again with x-odile-action: <id>'."},"risk":{"type":"number","description":"0-1. Present only when the project admin has set a risk model (PUT /admin/risk-model); omitted otherwise."},"risk_features":{"type":"array","maxItems":2,"description":"The up to 2 model features that moved the score most, present only alongside risk.","items":{"type":"object","properties":{"feature":{"type":"string"},"value":{},"contribution":{"type":"number"}}}},"job_id":{"type":"string","description":"Alias of action_id; identifies a held action, not an automatically executing job."},"status_url":{"type":"string","format":"uri-reference","description":"Relative GET status URL, also in Location. Requires the same app key and original run token if run-bound."}}},"AgentRun":{"type":"object","description":"What the run still allows (describeRun in src/runs.js).","properties":{"run_id":{"type":"string"},"app_id":{"type":"string"},"label":{"type":["string","null"]},"scope":{"type":"object","additionalProperties":{"type":"string"}},"parent_run_id":{"type":["string","null"]},"depth":{"type":"integer"},"expires_at":{"type":"string","format":"date-time"},"seconds_left":{"type":"integer"},"calls_left":{"type":["integer","null"],"description":"null = no run-wide cap"},"actions":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string","example":"PATCH /customers/{customer}/tickets/:id"},"approval_required":{"type":"boolean"},"calls_left":{"type":["integer","null"]},"recoverable":{"type":"boolean","description":"present (true) when the action was granted with a check, so POST /_gate/recover can answer for it"}}}},"writes_need":{"type":"string"},"state":{"type":"string","description":"Present on GET /_gate/run only: the run state."}}},"UnsupportedGateVersion":{"type":"object","required":["error","supported_versions"],"properties":{"error":{"type":"string","const":"unsupported Gate-Version"},"supported_versions":{"type":"array","items":{"type":"string","enum":["1"]}}}},"Onboarding":{"type":"object","required":["product","publisher","version","account_required","payment_required","free_plan","create_project","sandbox","docs_url","openapi_url"],"properties":{"product":{"type":"string","const":"Odile Gate"},"publisher":{"type":"string","const":"Odile Labs"},"version":{"type":"string","const":"1"},"account_required":{"type":"boolean","const":false},"payment_required":{"type":"boolean","const":false},"free_plan":{"type":"object","required":["apps","calls_per_month","audit_retention_days"],"properties":{"apps":{"type":"integer"},"calls_per_month":{"type":"integer"},"audit_retention_days":{"type":"integer"}}},"create_project":{"type":"object","required":["method","url","authentication","content_type","example","returns","note"],"properties":{"method":{"type":"string","const":"POST"},"url":{"type":"string","const":"/api/projects"},"authentication":{"type":"string","const":"none"},"content_type":{"type":"string","const":"application/json"},"example":{"$ref":"#/components/schemas/PubCreateProjectRequest"},"returns":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}}},"sandbox":{"type":"object","required":["name","upstream","internal_only","external_upstream_requests","persistent_project","uses_free_plan_allowance","description"],"properties":{"name":{"type":"string"},"upstream":{"type":"string","format":"uri"},"internal_only":{"type":"boolean","const":true},"external_upstream_requests":{"type":"boolean","const":false},"persistent_project":{"type":"boolean","const":true},"uses_free_plan_allowance":{"type":"boolean","const":true},"description":{"type":"string"}}},"docs_url":{"type":"string","format":"uri-reference"},"openapi_url":{"type":"string","format":"uri-reference"}}}},"headers":{"GateVersion":{"description":"Gate API compatibility version, including error responses.","schema":{"type":"string","enum":["1"]}},"Deprecation":{"description":"Only on a route scheduled for retirement: structured-field date (@ followed by Unix seconds). No route is currently deprecated.","schema":{"type":"string","pattern":"^@[0-9]+$"}},"Sunset":{"description":"Only on a route scheduled for retirement: HTTP-date after at least 90 days notice. Not emitted for current routes.","schema":{"type":"string"}},"ActionLocation":{"description":"Relative status URL for a Gate approval hold only. GET with the same app key and, for a run-bound action, the same run token. Not automatic execution.","schema":{"type":"string","format":"uri-reference"}},"CreationLimit":{"description":"3 requests per 60 seconds per IP, from the configured CREATE_LIMIT binding. Present only after that limiter runs.","schema":{"type":"integer","enum":[3]}},"CreationPolicy":{"description":"Actual project-creation policy. The binding exposes no remaining counter or reset timestamp.","schema":{"type":"string","enum":["\"project-create\";q=3;w=60"]}}}},"x-versioning-policy":{"strategy":"header","requestHeader":"Gate-Version","responseHeader":"Gate-Version","supportedVersions":["1"],"defaultVersion":"1","unsupportedVersionStatus":400,"scope":"All routes on the canonical host; not forwarded upstream.","breakingChanges":"A separately documented versioned replacement path; no silent repurposing.","deprecation":{"scheduled":false,"minimumNoticeDays":90,"signals":["OpenAPI deprecated: true","Deprecation","Sunset"],"policyUrl":"https://gate.odilelabs.com/docs#versions"}}}