{ "components": { "schemas": { "Envelope": { "properties": { "data": {}, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "meta" ], "type": "object" }, "ErrorEnvelope": { "properties": { "data": { "nullable": true }, "error": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "error", "meta" ], "type": "object" } }, "securitySchemes": { "bearerAuth": { "bearerFormat": "hq_live_\u003chex\u003e | jwt | agent_id", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Auto-generated from route handlers. See docs/integrations-sync/SCHEMA-MAINTENANCE.md.", "title": "MyAPI", "version": "1.0.0" }, "openapi": "3.0.3", "paths": { "/.well-known/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of .well-known: method, path, auth, params, error codes — public, no auth", "tags": [ ".well-known" ] } }, "/.well-known/oauth-authorization-server": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "OAuth authorization-server metadata (RFC 8414). How an MCP client discovers the connect flow: authorize, token and register endpoints, PKCE S256 only.", "tags": [ ".well-known" ] } }, "/.well-known/oauth-protected-resource": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "OAuth protected-resource metadata (RFC 9728). Points the MCP endpoint at its authorization server.", "tags": [ ".well-known" ] } }, "/admin/auth/domains/activate": { "post": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Activate a custom auth domain after TLS provisioning (admin).", "tags": [ "admin" ] } }, "/admin/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of admin: method, path, auth, params, error codes — public, no auth", "tags": [ "admin" ] } }, "/audience/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of audience: method, path, auth, params, error codes — public, no auth", "tags": [ "audience" ] } }, "/audience/orgs/{org_id}/audiences": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List all audiences belonging to the org", "tags": [ "audience" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "description": { "description": "Free-text description (optional).", "type": "string" }, "filter": { "description": "Filter the audience evaluates against; same shape as /people/search and /company/search bodies. Empty filter = all rows in the source (default confidence='high' still applies).", "properties": { "confidence": { "description": "Goldfox confidence tier(s): high (default — 96.4% of dataset, no UGC), low (UGC source — spot-check), very_low (UGC + freemail mismatch — probably drop). Pass explicit array to widen beyond the default high-only.", "items": { "description": "tier", "type": "string" }, "type": "array" }, "country": { "description": "Filter by ISO 3166-1 alpha-2 country code (e.g. US, DE, GB). Consensus across TLD + address + phone.", "items": { "description": "country code", "type": "string" }, "type": "array" }, "country_consistent": { "description": "If true, only rows where TLD + address + phone all agree on country. Highest-trust geo signal.", "type": "boolean" }, "email_type": { "description": "Filter by email_type: corporate / freemail / role_based / other_corporate. OR within array. (Ignored on /company/search.)", "items": { "description": "type", "type": "string" }, "type": "array" }, "has_c_level": { "description": "Row has ≥1 person with seniority = c_level.", "type": "boolean" }, "has_careers_page": { "description": "Row has /careers, /jobs, /stellen, /recrut, /karriere on at least one source URL — growth-stage proxy.", "type": "boolean" }, "has_decision_maker": { "description": "Row has ≥1 person with seniority IN (c_level, vp_director).", "type": "boolean" }, "has_investors_page": { "description": "Row has /investors or /ir/ — public-company / mature-org proxy.", "type": "boolean" }, "has_shop_page": { "description": "Row has /shop, /store, /products, /cart — e-commerce proxy.", "type": "boolean" }, "is_registered_entity": { "description": "companies[0].legal_form_country is not null — name has a recognised legal suffix (GmbH/Ltd/Inc/SARL/...).", "type": "boolean" }, "keyword": { "description": "Case-insensitive substring match on the row's domain.", "type": "string" }, "limit": { "description": "Max results to return (default 20, max 100).", "type": "integer" }, "min_headcount": { "description": "Row's headcount_lower_bound (= ARRAY_LENGTH(people)) must be at least this. Soft floor only — real headcount is usually larger.", "type": "integer" }, "min_link_confidence": { "description": "Drop people with link_confidence below this threshold (0–1). 1.0 = email-domain match (definitive); 0.5 = strong; lower = weak. Default: no threshold.", "type": "integer" }, "min_source_count": { "description": "Row must appear in at least this many distinct source URLs.", "type": "integer" }, "offset": { "description": "Offset for pagination (default 0).", "type": "integer" }, "seniority": { "description": "Filter by Goldfox seniority: c_level, vp_director, manager, senior_ic, ic. OR within array. (Ignored on /company/search.)", "items": { "description": "seniority", "type": "string" }, "type": "array" }, "tld_class": { "description": "Filter by TLD class: cctld / generic / vanity / low_trust / other.", "items": { "description": "class", "type": "string" }, "type": "array" } }, "type": "object" }, "name": { "description": "Display name for the audience.", "type": "string" }, "source": { "description": "Whether the filter resolves to people or companies. Defaults to 'people'.", "enum": [ "people", "company" ], "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "description": "Audience payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a saved audience. member_count is computed against the live Goldfox dataset at create time.", "tags": [ "audience" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /audience/orgs/{org_id}/audiences/{audience_id}", "reversible": true, "risk": "low" } } }, "/audience/orgs/{org_id}/audiences/{audience_id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "audience_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete an audience (204 on success)", "tags": [ "audience" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } }, "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "audience_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single audience", "tags": [ "audience" ] }, "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "audience_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "description": { "description": "New description.", "type": "string" }, "filter": { "description": "Filter the audience evaluates against; same shape as /people/search and /company/search bodies. Empty filter = all rows in the source (default confidence='high' still applies).", "properties": { "confidence": { "description": "Goldfox confidence tier(s): high (default — 96.4% of dataset, no UGC), low (UGC source — spot-check), very_low (UGC + freemail mismatch — probably drop). Pass explicit array to widen beyond the default high-only.", "items": { "description": "tier", "type": "string" }, "type": "array" }, "country": { "description": "Filter by ISO 3166-1 alpha-2 country code (e.g. US, DE, GB). Consensus across TLD + address + phone.", "items": { "description": "country code", "type": "string" }, "type": "array" }, "country_consistent": { "description": "If true, only rows where TLD + address + phone all agree on country. Highest-trust geo signal.", "type": "boolean" }, "email_type": { "description": "Filter by email_type: corporate / freemail / role_based / other_corporate. OR within array. (Ignored on /company/search.)", "items": { "description": "type", "type": "string" }, "type": "array" }, "has_c_level": { "description": "Row has ≥1 person with seniority = c_level.", "type": "boolean" }, "has_careers_page": { "description": "Row has /careers, /jobs, /stellen, /recrut, /karriere on at least one source URL — growth-stage proxy.", "type": "boolean" }, "has_decision_maker": { "description": "Row has ≥1 person with seniority IN (c_level, vp_director).", "type": "boolean" }, "has_investors_page": { "description": "Row has /investors or /ir/ — public-company / mature-org proxy.", "type": "boolean" }, "has_shop_page": { "description": "Row has /shop, /store, /products, /cart — e-commerce proxy.", "type": "boolean" }, "is_registered_entity": { "description": "companies[0].legal_form_country is not null — name has a recognised legal suffix (GmbH/Ltd/Inc/SARL/...).", "type": "boolean" }, "keyword": { "description": "Case-insensitive substring match on the row's domain.", "type": "string" }, "limit": { "description": "Max results to return (default 20, max 100).", "type": "integer" }, "min_headcount": { "description": "Row's headcount_lower_bound (= ARRAY_LENGTH(people)) must be at least this. Soft floor only — real headcount is usually larger.", "type": "integer" }, "min_link_confidence": { "description": "Drop people with link_confidence below this threshold (0–1). 1.0 = email-domain match (definitive); 0.5 = strong; lower = weak. Default: no threshold.", "type": "integer" }, "min_source_count": { "description": "Row must appear in at least this many distinct source URLs.", "type": "integer" }, "offset": { "description": "Offset for pagination (default 0).", "type": "integer" }, "seniority": { "description": "Filter by Goldfox seniority: c_level, vp_director, manager, senior_ic, ic. OR within array. (Ignored on /company/search.)", "items": { "description": "seniority", "type": "string" }, "type": "array" }, "tld_class": { "description": "Filter by TLD class: cctld / generic / vanity / low_trust / other.", "items": { "description": "class", "type": "string" }, "type": "array" } }, "type": "object" }, "name": { "description": "New display name.", "type": "string" } }, "type": "object" } } }, "description": "Audience patch (all fields optional)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Update an audience's name / description / filter (re-evaluates member_count if filter changes)", "tags": [ "audience" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/audience/orgs/{org_id}/audiences/{audience_id}/members": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "audience_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get paged members of an audience. Returns people or companies depending on source.", "tags": [ "audience" ] } }, "/audience/orgs/{org_id}/audiences/{audience_id}/refresh": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "audience_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Re-evaluate the audience filter against current data and update member_count. Returns delta vs previous.", "tags": [ "audience" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/auth/google/callback": { "get": { "parameters": [ { "description": "Authorization code returned by Google.", "in": "query", "name": "code", "required": false, "schema": { "type": "string" } }, { "description": "Opaque state echoed back by Google; verified before use.", "in": "query", "name": "state", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Managed-Google OAuth callback — completes end-user sign-in and returns an OIDC code to the customer app.", "tags": [ "auth" ] } }, "/auth/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of auth: method, path, auth, params, error codes — public, no auth", "tags": [ "auth" ] } }, "/auth/orgs/{org_id}/clients": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Rows per page (1..500, default 50). Out-of-range values are rejected with 400 rather than clamped.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Keyset cursor — pass the previous page's meta.next_cursor. Absent on the last page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List the OIDC clients registered for your org.", "tags": [ "auth" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "Human label for the client.", "type": "string" }, "redirect_uris": { "description": "Allowed post-login redirect URLs (absolute https, or http://localhost).", "items": { "description": "redirect_uri", "type": "string" }, "type": "array" }, "type": { "description": "Client type", "enum": [ "spa", "web" ], "type": "string" } }, "required": [ "name", "type", "redirect_uris" ], "type": "object" } } }, "description": "OIDC client", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "TENANT_NOT_FOUND", "REDIRECT_URIS_REQUIRED", "INVALID_REDIRECT_URI", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `TENANT_NOT_FOUND` — This org has no auth tenant yet. Create one first.; `REDIRECT_URIS_REQUIRED` — At least one redirect URI is required. Nothing was created.; `INVALID_REDIRECT_URI` — A redirect URI is not usable — see the message. Nothing was created.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Register an OIDC client for your app. Returns client_id (and client_secret ONCE for type=web). type: 'spa' (public, PKCE) | 'web' (confidential).", "tags": [ "auth" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /auth/orgs/{org_id}/clients/{client_id}", "reversible": true, "risk": "low" } } }, "/auth/orgs/{org_id}/clients/{client_id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "client_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete (revoke) an OIDC client.", "tags": [ "auth" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } }, "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "client_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "Label for your own reference.", "type": "string" }, "redirect_uris": { "description": "The complete list of allowed callback URLs. Each must be an absolute https URL, or http://localhost for development. Replaces what is there.", "items": { "description": "uri", "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Client changes", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "CLIENT_NOT_FOUND", "NOTHING_TO_UPDATE", "REDIRECT_URIS_REQUIRED", "INVALID_REDIRECT_URI", "NAME_REQUIRED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `CLIENT_NOT_FOUND` — No client with that id in this org.; `NOTHING_TO_UPDATE` — Send name or redirect_uris.; `REDIRECT_URIS_REQUIRED` — The list cannot be empty — a client with no redirect URI can never complete a sign-in.; `INVALID_REDIRECT_URI` — Each entry must be an absolute https URL, or http://localhost.; `NAME_REQUIRED` — name cannot be empty.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Change an OIDC client's redirect URIs or name, keeping the SAME client_id and secret. Before this existed the only way to add a callback URL was to delete the client and create another — which mints a new client_id, so every deployed copy of your app has to be reconfigured, and you have to accept two audiences during the cutover. redirect_uris REPLACES the list: send all of them, including the ones you are keeping.", "tags": [ "auth" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/auth/orgs/{org_id}/clients/{client_id}/rotate": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "client_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Rotate a confidential ('web') client's secret. Returns the new client_secret ONCE; the old secret stops working immediately.", "tags": [ "auth" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/auth/orgs/{org_id}/domain": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Remove your custom auth domain.", "tags": [ "auth" ], "x-safety": { "denylist": true, "disclosure": "live_site_change", "kind": "mutate", "reversible": false, "risk": "high" } }, "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get your custom auth domain + status (awaiting_verification|pending|active).", "tags": [ "auth" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "domain": { "description": "Hostname you control, e.g. auth.acme.com", "type": "string" } }, "required": [ "domain" ], "type": "object" } } }, "description": "Custom domain", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_DOMAIN", "DOMAIN_NOT_VERIFIED", "NO_DOMAIN", "TENANT_NOT_FOUND", "DOMAIN_EXISTS", "DOMAIN_TAKEN", "RESERVED_DOMAIN", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_DOMAIN` — That is not a usable domain name. Nothing was changed.; `DOMAIN_NOT_VERIFIED` — The domain is not verified yet. Add the TXT record shown, then POST .../domain/verify.; `NO_DOMAIN` — No domain is set for this tenant.; `TENANT_NOT_FOUND` — This org has no auth tenant yet. Create one with POST /auth/orgs/{org_id}/tenant.; `DOMAIN_EXISTS` — This auth domain is already registered for the org.; `DOMAIN_TAKEN` — The domain is used by a different org. Pick another.; `RESERVED_DOMAIN` — The domain is reserved by the platform. Pick another.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Register a custom auth domain (e.g. auth.acme.com). Returns the DNS record to create; TLS is provisioned, then it becomes your issuer.", "tags": [ "auth" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /auth/orgs/{org_id}/domain", "reversible": true, "risk": "low" } } }, "/auth/orgs/{org_id}/domain/verify": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Verify ownership of your custom auth domain by checking the challenge TXT record. Advances awaiting_verification → pending.", "tags": [ "auth" ], "x-safety": { "denylist": false, "kind": "mutate", "proof": [ "dns" ], "reversible": false, "risk": "low" } } }, "/auth/orgs/{org_id}/tenant": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "TENANT_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `TENANT_NOT_FOUND` — This org has no auth tenant yet. Create one with POST /auth/orgs/{org_id}/tenant.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get your org's auth tenant (issuer + login URL).", "tags": [ "auth" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "connections": { "description": "Sign-in methods to enable", "items": { "description": "Connection", "enum": [ "google", "password" ], "type": "string" }, "type": "array" }, "theme": { "additionalProperties": true, "description": "Hosted login-page theme tokens", "type": "object" } }, "type": "object" } } }, "description": "Tenant configuration", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Provision (or re-read) your org's auth tenant. The org IS the auth tenant; end-users then sign in via MyAPI's managed Google app (no GCP account needed). Returns the issuer + login URL.", "tags": [ "auth" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/auth/orgs/{org_id}/usage": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Current-period monthly-active-end-user (MAU) count + per-MAU price for your org.", "tags": [ "auth" ] } }, "/auth/orgs/{org_id}/users": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List this tenant's end-users, most-recently-active first, each with the product capabilities granted to them. This is how you find a user's id to grant or revoke authority.", "tags": [ "auth" ] } }, "/auth/orgs/{org_id}/users/{user_id}/capabilities": { "put": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "user_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "capabilities": { "description": "The product capabilities to grant this user — report | edit_content | propose_change | apply_change. Replaces the current set; [] revokes all.", "items": { "description": "A capability", "type": "string" }, "type": "array" } }, "required": [ "capabilities" ], "type": "object" } } }, "description": "The capabilities to grant", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_CAPABILITY", "NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_CAPABILITY` — A capability is not one of report, edit_content, propose_change, apply_change. Nothing was changed.; `NOT_FOUND` — No user with that id in this tenant.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Grant or revoke an end-user's authority OVER YOUR PRODUCT. This is a SEPARATE namespace from any role your product defines for its own users — it says what this person may do to the product itself. The set is replaced; send [] to revoke. Granted capabilities appear as the verified myapi_capabilities claim in the user's id_token and /userinfo, so enforce them server-side, never from a hidden button. Allowed: report, edit_content, propose_change, apply_change.", "tags": [ "auth" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "PUT /auth/orgs/{org_id}/users/{user_id}/capabilities", "reversible": true, "risk": "high" } } }, "/auth/{tenant}/.well-known/openid-configuration": { "get": { "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "OIDC discovery document for a tenant.", "tags": [ "auth" ] } }, "/auth/{tenant}/authorize": { "get": { "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "description": "OAuth client id. Required.", "in": "query", "name": "client_id", "required": true, "schema": { "type": "string" } }, { "description": "Registered redirect URI. Required, and must match a registered value exactly.", "in": "query", "name": "redirect_uri", "required": true, "schema": { "type": "string" } }, { "description": "Must be `code` — this is an authorization-code flow.", "in": "query", "name": "response_type", "required": true, "schema": { "type": "string" } }, { "description": "PKCE challenge. Required.", "in": "query", "name": "code_challenge", "required": true, "schema": { "type": "string" } }, { "description": "Must be `S256`. `plain` is refused.", "in": "query", "name": "code_challenge_method", "required": true, "schema": { "type": "string" } }, { "description": "Space-separated scopes.", "in": "query", "name": "scope", "required": false, "schema": { "type": "string" } }, { "description": "Opaque value returned unchanged on the redirect. Use it for CSRF protection.", "in": "query", "name": "state", "required": false, "schema": { "type": "string" } }, { "description": "Value bound into the issued id_token.", "in": "query", "name": "nonce", "required": false, "schema": { "type": "string" } }, { "description": "Pre-select an identity provider instead of showing the chooser.", "in": "query", "name": "connection", "required": false, "schema": { "type": "string" } }, { "description": "Pre-fills the email field on the rendered login page.", "in": "query", "name": "email", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "OIDC authorize endpoint — validates the request and starts the hosted login flow (managed Google).", "tags": [ "auth" ] } }, "/auth/{tenant}/forgot-password": { "get": { "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Password-reset request page (enter email).", "tags": [ "auth" ] } }, "/auth/{tenant}/jwks": { "get": { "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "JWKS — token-signing public keys.", "tags": [ "auth" ] } }, "/auth/{tenant}/magic/callback": { "get": { "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "description": "Single-use token from the magic-link email. Required.", "in": "query", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Complete passwordless sign-in from the emailed link — returns an OIDC code to the customer app.", "tags": [ "auth" ] } }, "/auth/{tenant}/magic/start": { "post": { "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "client_id": { "description": "OIDC client id for this tenant", "type": "string" }, "code_challenge": { "description": "PKCE challenge. Required — PKCE is mandatory for every client.", "type": "string" }, "code_challenge_method": { "description": "PKCE method. Only S256 is accepted.", "enum": [ "S256" ], "type": "string" }, "email": { "description": "End-user email address", "type": "string" }, "nonce": { "description": "Opaque value bound into the id_token", "type": "string" }, "redirect_uri": { "description": "Must exactly match a redirect URI registered for the client", "type": "string" }, "response_type": { "description": "Only the authorization-code flow is supported", "enum": [ "code" ], "type": "string" }, "scope": { "description": "Space-separated scopes (default \"openid email profile\")", "type": "string" }, "state": { "description": "Opaque value echoed back to your app — use it for CSRF protection", "type": "string" } }, "required": [ "email", "client_id", "redirect_uri", "response_type", "code_challenge", "code_challenge_method" ], "type": "object" } } }, "description": "Address plus the OIDC parameters from /authorize. Send form-encoded or JSON.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Email a one-time passwordless sign-in link.", "tags": [ "auth" ] } }, "/auth/{tenant}/password/login": { "post": { "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "client_id": { "description": "OIDC client id for this tenant", "type": "string" }, "code_challenge": { "description": "PKCE challenge. Required — PKCE is mandatory for every client.", "type": "string" }, "code_challenge_method": { "description": "PKCE method. Only S256 is accepted.", "enum": [ "S256" ], "type": "string" }, "email": { "description": "End-user email address", "type": "string" }, "nonce": { "description": "Opaque value bound into the id_token", "type": "string" }, "password": { "description": "End-user password", "type": "string" }, "redirect_uri": { "description": "Must exactly match a redirect URI registered for the client", "type": "string" }, "response_type": { "description": "Only the authorization-code flow is supported", "enum": [ "code" ], "type": "string" }, "scope": { "description": "Space-separated scopes (default \"openid email profile\")", "type": "string" }, "state": { "description": "Opaque value echoed back to your app — use it for CSRF protection", "type": "string" } }, "required": [ "email", "password", "client_id", "redirect_uri", "response_type", "code_challenge", "code_challenge_method" ], "type": "object" } } }, "description": "Credentials plus the OIDC parameters from /authorize. Send form-encoded or JSON.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Email/password sign-in — returns an OIDC code to the customer app.", "tags": [ "auth" ] } }, "/auth/{tenant}/password/reset": { "post": { "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "password": { "description": "The new password", "type": "string" }, "token": { "description": "Token from the emailed reset link", "type": "string" } }, "required": [ "token", "password" ], "type": "object" } } }, "description": "Reset token plus the new password. Send form-encoded or JSON.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Set a new password from a valid reset token; revokes existing sessions.", "tags": [ "auth" ] } }, "/auth/{tenant}/password/reset-request": { "post": { "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "description": "End-user email address", "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "description": "Address to send the reset link to. Send form-encoded or JSON.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Send a password-reset link (anti-enumeration: identical response whether or not the email exists).", "tags": [ "auth" ] } }, "/auth/{tenant}/password/signup": { "post": { "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "client_id": { "description": "OIDC client id for this tenant", "type": "string" }, "code_challenge": { "description": "PKCE challenge. Required — PKCE is mandatory for every client.", "type": "string" }, "code_challenge_method": { "description": "PKCE method. Only S256 is accepted.", "enum": [ "S256" ], "type": "string" }, "email": { "description": "End-user email address", "type": "string" }, "nonce": { "description": "Opaque value bound into the id_token", "type": "string" }, "password": { "description": "End-user password", "type": "string" }, "redirect_uri": { "description": "Must exactly match a redirect URI registered for the client", "type": "string" }, "response_type": { "description": "Only the authorization-code flow is supported", "enum": [ "code" ], "type": "string" }, "scope": { "description": "Space-separated scopes (default \"openid email profile\")", "type": "string" }, "state": { "description": "Opaque value echoed back to your app — use it for CSRF protection", "type": "string" } }, "required": [ "email", "password", "client_id", "redirect_uri", "response_type", "code_challenge", "code_challenge_method" ], "type": "object" } } }, "description": "Credentials plus the OIDC parameters from /authorize. Send form-encoded or JSON.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Email/password sign-up — creates an end-user, sends a verification email, returns an OIDC code.", "tags": [ "auth" ] } }, "/auth/{tenant}/reset-password": { "get": { "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "description": "Single-use token from the reset email. Required.", "in": "query", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Set-a-new-password page (from the reset link).", "tags": [ "auth" ] } }, "/auth/{tenant}/token": { "post": { "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "client_id": { "description": "OIDC client id", "type": "string" }, "client_secret": { "description": "Client secret — confidential clients only", "type": "string" }, "code": { "description": "The authorization code (grant_type=authorization_code)", "type": "string" }, "code_verifier": { "description": "PKCE verifier matching the challenge sent to /authorize", "type": "string" }, "grant_type": { "description": "Which grant to exercise", "enum": [ "authorization_code", "refresh_token" ], "type": "string" }, "redirect_uri": { "description": "Must match the redirect_uri used at /authorize (grant_type=authorization_code)", "type": "string" }, "refresh_token": { "description": "The refresh token to exchange (grant_type=refresh_token)", "type": "string" } }, "required": [ "grant_type", "client_id" ], "type": "object" } } }, "description": "Token request. Send form-encoded or JSON. Fields depend on grant_type.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "OIDC token endpoint (authorization_code + refresh). TOKEN SHAPES — verify the id_token for identity: its aud is the client id and it carries azp. The access_token is a bearer credential for this tenant's userinfo endpoint, so its aud is \u003cissuer\u003e/userinfo, NOT the client id; checking aud==client_id against it rejects every valid token. It also carries azp=\u003cclient id\u003e so it can be attributed to a client, plus tenant and scope. Both are RS256, verifiable against \u003cissuer\u003e/jwks.", "tags": [ "auth" ] } }, "/auth/{tenant}/userinfo": { "get": { "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "OIDC userinfo endpoint.", "tags": [ "auth" ] } }, "/auth/{tenant}/verify-email": { "get": { "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "description": "Single-use token from the verification email. Required.", "in": "query", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Confirm an end-user's email from the verification link.", "tags": [ "auth" ] } }, "/billing/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of billing: method, path, auth, params, error codes — public, no auth", "tags": [ "billing" ] } }, "/billing/recharge": { "post": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RECHARGE_RUNTIME_ONLY", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RECHARGE_RUNTIME_ONLY` — Only a deployed function or container can trigger recharge. Call this from deployed code.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Trigger this account's configured auto-recharge. For deployed functions and containers only, called by the runtime shim when a request is refused for low balance. Carries no amount and no card details: it fires the saved auto-recharge policy through the guarded refill path, or reports why it did not (disabled, no_card, above_threshold). The refill is off-session, so a success here means it was started; wait briefly and retry once.", "tags": [ "billing" ] } }, "/comments/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of comments: method, path, auth, params, error codes — public, no auth", "tags": [ "comments" ] } }, "/comments/in/{key}": { "get": { "parameters": [ { "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "description": "Only comments for this page or section.", "in": "query", "name": "route", "required": false, "schema": { "type": "string" } }, { "description": "approved_at of the last comment you saw, as returned in next_cursor.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Comments per page (1..100, default 50).", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "KEY_NOT_FOUND", "LIMIT_INVALID", "CURSOR_INVALID" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `KEY_NOT_FOUND` — No comments key with that key.; `LIMIT_INVALID` — limit must be 1..100.; `CURSOR_INVALID` — cursor is the approved_at value from next_cursor." } }, "summary": "Public: the approved comments for a key, oldest approval first, with exactly these fields: id, route, display_name, body, reply, created_at, approved_at. Pending, rejected, withdrawn, erased and test comments never appear. A revoked key answers an empty list. Sends ETag and a short max-age so a busy page is cheap.", "tags": [ "comments" ] }, "post": { "parameters": [ { "in": "path", "name": "key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "body": { "description": "The comment, plain text, at most 8000 characters (or the key's body_max).", "type": "string" }, "consent": { "description": "Whether the page's terms were accepted. The page states them; this records the flag.", "type": "boolean" }, "display_name": { "description": "The name shown with the comment, 2 to 60 characters.", "type": "string" }, "email": { "description": "Optional. Never public; only to tell the writer when it is approved.", "type": "string" }, "route": { "description": "Which page or section it belongs to, e.g. /article-3 or /#section-2. Filterable on read.", "type": "string" }, "test": { "description": "Flag the comment as test: it never appears on the public read and never counts.", "type": "boolean" } }, "required": [ "display_name", "body" ], "type": "object" } } }, "description": "The comment", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "KEY_NOT_FOUND", "ORIGIN_NOT_ALLOWED", "RATE_LIMITED", "INVALID_BODY", "NAME_REQUIRED", "BODY_REQUIRED", "BODY_TOO_LONG", "EMAIL_INVALID" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `KEY_NOT_FOUND` — No active comments key with that key. Nothing was recorded.; `ORIGIN_NOT_ALLOWED` — This key does not accept comments from that origin. Nothing was recorded.; `RATE_LIMITED` — Too many comments from this address. Wait a minute. Nothing was recorded.; `INVALID_BODY` — The body is not valid JSON. Nothing was recorded.; `NAME_REQUIRED` — display_name is required, 2 to 60 characters. Nothing was recorded.; `BODY_REQUIRED` — body is required. Nothing was recorded.; `BODY_TOO_LONG` — body is over the limit. Nothing was recorded.; `EMAIL_INVALID` — email is not a valid address. Nothing was recorded." } }, "summary": "Public: submit a comment under a site's key. It lands as pending and is not visible to anyone until the org approves it. The answer is the id and the status, nothing else. Rate-limited per key and address; origin-checked when the key has allowed_origins.", "tags": [ "comments" ] } }, "/comments/orgs/{org_id}/items": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "pending, approved, rejected, withdrawn or erased.", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "description": "Only comments for this page or section.", "in": "query", "name": "route", "required": false, "schema": { "type": "string" } }, { "description": "Only comments submitted under this key id.", "in": "query", "name": "key", "required": false, "schema": { "type": "string" } }, { "description": "created_at of the last row you saw, as returned in next_cursor.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Rows per page (1..500, default 50).", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "STATUS_INVALID", "LIMIT_INVALID", "CURSOR_INVALID", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `STATUS_INVALID` — status must be pending, approved, rejected, withdrawn or erased.; `LIMIT_INVALID` — limit must be 1..500.; `CURSOR_INVALID` — cursor is the created_at value from next_cursor.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "The org's comments with every field, private ones included (email, ip, user_agent, origin, reason, who decided and when), newest first. Filter by status, route and key. This is the moderation queue: status=pending is what waits for you.", "tags": [ "comments" ] } }, "/comments/orgs/{org_id}/items/{id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "COMMENT_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `COMMENT_NOT_FOUND` — No comment with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Erase a comment's personal data: body, name, email, address, user agent, origin, reply and reason are wiped for good. A tombstone {id, status: erased, at} stays so the record has no holes. This cannot be undone. Idempotent. Answers 200 with the tombstone (not 204) so you can keep it.", "tags": [ "comments" ], "x-safety": { "denylist": false, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/comments/orgs/{org_id}/items/{id}/approve": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reply": { "description": "The org's public answer, shown under the comment. At most 4000 characters.", "type": "string" } }, "type": "object" } } }, "description": "Optional reply", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "COMMENT_NOT_FOUND", "COMMENT_NOT_PENDING", "INVALID_BODY", "REPLY_TOO_LONG", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `COMMENT_NOT_FOUND` — No comment with that id in this org.; `COMMENT_NOT_PENDING` — Only a pending comment can be approved. Nothing was changed.; `INVALID_BODY` — The body is not valid JSON. Nothing was changed.; `REPLY_TOO_LONG` — reply is at most 4000 characters. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Publish a pending comment: from now on anyone reading the page sees it. Optional reply is published under it. Idempotent on an already-approved comment. Refused from rejected, withdrawn or erased. Approving makes text visible to the public: say so when you agree to it.", "tags": [ "comments" ], "x-safety": { "denylist": false, "disclosure": "data_visible_publicly", "kind": "mutate", "reverse": "POST /comments/orgs/{org_id}/items/{id}/withdraw", "reversible": true, "risk": "high" } } }, "/comments/orgs/{org_id}/items/{id}/reject": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Why, for your own records. Never public. At most 1000 characters.", "type": "string" } }, "type": "object" } } }, "description": "Optional reason", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "COMMENT_NOT_FOUND", "COMMENT_NOT_PENDING", "INVALID_BODY", "REASON_TOO_LONG", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `COMMENT_NOT_FOUND` — No comment with that id in this org.; `COMMENT_NOT_PENDING` — Only a pending comment can be rejected. Nothing was changed.; `INVALID_BODY` — The body is not valid JSON. Nothing was changed.; `REASON_TOO_LONG` — reason is at most 1000 characters. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Decline a pending comment. The optional reason stays private to the org. Idempotent on an already-rejected comment.", "tags": [ "comments" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/comments/orgs/{org_id}/items/{id}/withdraw": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Why, for your own records. Never public. At most 1000 characters.", "type": "string" } }, "type": "object" } } }, "description": "Optional reason", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "COMMENT_NOT_FOUND", "COMMENT_NOT_APPROVED", "INVALID_BODY", "REASON_TOO_LONG", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `COMMENT_NOT_FOUND` — No comment with that id in this org.; `COMMENT_NOT_APPROVED` — Only an approved comment can be withdrawn. Nothing was changed.; `INVALID_BODY` — The body is not valid JSON. Nothing was changed.; `REASON_TOO_LONG` — reason is at most 1000 characters. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Take an approved comment off the public read at once. The reverse of approve. The text and the decision history stay for the org; the optional reason stays private. Idempotent on an already-withdrawn comment.", "tags": [ "comments" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/comments/orgs/{org_id}/keys": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List the org's comments keys in full, newest first. Keys are public by construction.", "tags": [ "comments" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "allowed_origins": { "description": "Origins that may post and read with this key, e.g. https://example.com. Empty means any.", "type": "string" }, "body_max": { "description": "Per-comment character cap for this key, 100..8000. Default 8000.", "type": "integer" }, "moderation": { "description": "How comments become public. \"pre\" (the default, and the only value served today): every comment waits for approve. \"post\" is accepted by the schema and refused at runtime with MODERATION_UNSUPPORTED until it is built.", "enum": [ "pre", "post" ], "type": "string" }, "name": { "description": "A label for you. Default \"comments\".", "type": "string" }, "rate_per_minute": { "description": "Per-address cap for this key, 1..600. Default: the platform's.", "type": "integer" } }, "type": "object" } } }, "description": "The key", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_BODY", "MODERATION_UNSUPPORTED", "MODERATION_INVALID", "ORIGIN_INVALID", "RATE_INVALID", "BODY_MAX_INVALID", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_BODY` — The body is not valid JSON. Nothing was created.; `MODERATION_UNSUPPORTED` — moderation \"post\" is not available yet. Use \"pre\". Nothing was created.; `MODERATION_INVALID` — moderation must be \"pre\" or \"post\". Nothing was created.; `ORIGIN_INVALID` — An allowed_origins entry is not an origin. Nothing was created.; `RATE_INVALID` — rate_per_minute must be 1..600. Nothing was created.; `BODY_MAX_INVALID` — body_max must be 100..8000. Nothing was created.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Mint a public key for a site. The key ships in page source: it names the org and can be revoked; it is not a secret. allowed_origins limits which sites may post with it. moderation is \"pre\": nothing is public before approve.", "tags": [ "comments" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /comments/orgs/{org_id}/keys/{id}", "reversible": true, "risk": "low" } } }, "/comments/orgs/{org_id}/keys/{id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "KEY_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `KEY_NOT_FOUND` — No comments key with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Revoke a key. Submissions stop at once; the comments stay; the public read for that key answers an empty list, not an error, so a page that still ships the key keeps working. 204.", "tags": [ "comments" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } }, "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "allowed_origins": { "description": "Replaces the list. Empty list means any origin.", "type": "string" }, "body_max": { "description": "100..8000.", "type": "integer" }, "name": { "description": "New label.", "type": "string" }, "rate_per_minute": { "description": "1..600.", "type": "integer" } }, "type": "object" } } }, "description": "Fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "KEY_NOT_FOUND", "INVALID_BODY", "NAME_REQUIRED", "MODERATION_UNSUPPORTED", "ORIGIN_INVALID", "RATE_INVALID", "BODY_MAX_INVALID", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `KEY_NOT_FOUND` — No comments key with that id in this org.; `INVALID_BODY` — The body is not valid JSON. Nothing was changed.; `NAME_REQUIRED` — name cannot be empty. Nothing was changed.; `MODERATION_UNSUPPORTED` — moderation \"post\" is not available yet. Nothing was changed.; `ORIGIN_INVALID` — An allowed_origins entry is not an origin. Nothing was changed.; `RATE_INVALID` — rate_per_minute must be 1..600. Nothing was changed.; `BODY_MAX_INVALID` — body_max must be 100..8000. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Change a key's name, origins or limits. Omitted fields keep their value; allowed_origins, when sent, replaces the list.", "tags": [ "comments" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/company/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of company: method, path, auth, params, error codes — public, no auth", "tags": [ "company" ] } }, "/company/orgs/{org_id}/search": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "confidence": { "description": "Goldfox confidence tier(s): high (default — 96.4% of dataset, no UGC), low (UGC source — spot-check), very_low (UGC + freemail mismatch — probably drop). Pass explicit array to widen beyond the default high-only.", "items": { "description": "tier", "type": "string" }, "type": "array" }, "country": { "description": "Filter by ISO 3166-1 alpha-2 country code (e.g. US, DE, GB). Consensus across TLD + address + phone.", "items": { "description": "country code", "type": "string" }, "type": "array" }, "country_consistent": { "description": "If true, only rows where TLD + address + phone all agree on country. Highest-trust geo signal.", "type": "boolean" }, "has_c_level": { "description": "Row has ≥1 person with seniority = c_level.", "type": "boolean" }, "has_careers_page": { "description": "Row has /careers, /jobs, /stellen, /recrut, /karriere on at least one source URL — growth-stage proxy.", "type": "boolean" }, "has_decision_maker": { "description": "Row has ≥1 person with seniority IN (c_level, vp_director).", "type": "boolean" }, "has_investors_page": { "description": "Row has /investors or /ir/ — public-company / mature-org proxy.", "type": "boolean" }, "has_shop_page": { "description": "Row has /shop, /store, /products, /cart — e-commerce proxy.", "type": "boolean" }, "include_people": { "description": "If \u003e0, embed up to N representative people per company in the response (max 10).", "type": "integer" }, "is_registered_entity": { "description": "companies[0].legal_form_country is not null — name has a recognised legal suffix (GmbH/Ltd/Inc/SARL/...).", "type": "boolean" }, "keyword": { "description": "Case-insensitive substring match on the row's domain.", "type": "string" }, "limit": { "description": "Max results to return (default 20, max 100).", "type": "integer" }, "min_headcount": { "description": "Row's headcount_lower_bound (= ARRAY_LENGTH(people)) must be at least this. Soft floor only — real headcount is usually larger.", "type": "integer" }, "min_source_count": { "description": "Row must appear in at least this many distinct source URLs.", "type": "integer" }, "offset": { "description": "Offset for pagination (default 0).", "type": "integer" }, "tld_class": { "description": "Filter by TLD class: cctld / generic / vanity / low_trust / other.", "items": { "description": "class", "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Company search filter (Goldfox-native)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Search companies in the Goldfox dataset by country / org signals / TLD class", "tags": [ "company" ], "x-safety": { "denylist": false, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/company/orgs/{org_id}/{company_id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "company_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "COMPANY_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `COMPANY_NOT_FOUND` — No company with that id.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single company by its domain (e.g. /company/orgs/.../acme.de). Pass ?include_people=N to embed people.", "tags": [ "company" ] } }, "/console": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "The Sabaki story view: goals, outcomes, claims with evidence, and the controls — a self-contained page for a person, not an API.", "tags": [ "console" ] } }, "/console/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of console: method, path, auth, params, error codes — public, no auth", "tags": [ "console" ] } }, "/container/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of container: method, path, auth, params, error codes — public, no auth", "tags": [ "container" ] } }, "/container/orgs/{org_id}/containers": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Rows per page (1..500, default 50). Out-of-range values are rejected with 400 rather than clamped — a caller who asks for 5000 and silently gets 500 believes they have the whole list.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Keyset cursor — pass the previous page's meta.next_cursor. Absent on the last page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List containers for the org", "tags": [ "container" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "cpu": { "description": "vCPU: 1, 2, 4 (default 1)", "type": "string" }, "cron_schedule": { "description": "Cron expression; valid only for type=job", "type": "string" }, "env": { "additionalProperties": true, "description": "Environment variables, name → value. Set HERE: deploy cannot change them.", "type": "object" }, "health_check": { "description": "Path for the startup probe, for example \"/livez\". The runtime waits for this to answer before the revision is considered ready, and it is returned on GET so you can confirm it. NOT /healthz — that path is answered before it reaches your container, so a probe against it passes even when your app is down, and it is refused. Without it the probe is a bare TCP connect, which only proves something is listening — a process that binds the port and serves nonsense looks identical to a working one. /healthz is REFUSED: the runtime intercepts it, so it never reaches your container and the probe would always pass.", "type": "string" }, "max_instances": { "description": "Upper bound on horizontal scale (default 3). Each instance holds its own memory.", "type": "integer" }, "memory": { "description": "Memory: 512Mi, 1Gi, 2Gi, 4Gi (default 512Mi)", "type": "string" }, "min_instances": { "description": "Instances kept warm (default 0 — the service scales to zero).", "type": "integer" }, "name": { "description": "Kebab-case slug, 1-50 chars; reserved: www, api, admin, system, default", "type": "string" }, "port": { "description": "Port your container listens on (default 8080).", "type": "integer" }, "scopes": { "description": "Optional slot allow-list for the minted key, e.g. [\"crm\",\"email\"]; empty = inherit the caller's grants", "type": "string" }, "ttl_hours": { "description": "Make the container ephemeral: it is torn down (runtime, key, custom domain — the same teardown as DELETE) when the time is up, whatever happened to its creator. 1 to 168; 0 or omitted means it lives until deleted. Sweep runs every few minutes, so treat the TTL as a cleanup contract, not a deadline. The container's expires_at is returned on create and GET.", "type": "integer" }, "type": { "description": "Runtime type", "enum": [ "service", "worker", "job" ], "type": "string" }, "visibility": { "description": "public (default) or private. A private container deploys with internal-only ingress and no public invoker — it gets NO public URL and cannot be reached from the internet, which is the right posture for running code whose configuration must not be exposed. Reaching a private container from elsewhere is separate work; today it is addressable only from inside the platform. Immutable after create.", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "description": "Container creation payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NAME_TAKEN", "INVALID_TTL", "INVALID_VISIBILITY", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NAME_TAKEN` — A container with that name already exists in this org. Pick another.; `INVALID_TTL` — ttl_hours must be between 1 and 168, or 0 for no expiry.; `INVALID_VISIBILITY` — visibility must be public or private.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a container — persists metadata and mints a scoped API key (returned ONCE). The key is org-locked and its slot grants are limited to the optional 'scopes' allow-list — the key is delivered to the running container as MYAPI_KEY, so request only the slots it needs. Omitting scopes inherits the caller's grants; scopes can never exceed the caller's. Deploy it with POST .../containers/{id}/deploy. RUNTIME CONSTRAINTS, all of which have bitten people: a type=service is horizontally scaled and STATELESS — it scales to zero AND up to max_instances (default 3), each instance holding its own memory, so in-process state returns wrong answers under concurrency rather than erroring. The path /healthz is intercepted by the runtime and never reaches your container — use /livez or any other path. Request bodies are capped at 32MB. Any 5xx from your origin is replaced by the edge with an HTML error page, so a JSON error envelope will not reach the client; return 4xx if the reason must survive. env, cpu, memory, max_instances and cron_schedule are set HERE and cannot be changed by deploy.", "tags": [ "container" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /container/orgs/{org_id}/containers/{id}", "reversible": true, "risk": "low" } } }, "/container/orgs/{org_id}/containers/{id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete a container (soft-delete + revoke scoped API key + tear down the running service)", "tags": [ "container" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } }, "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Set to true to return environment values instead of \"set\". Default false.", "in": "query", "name": "reveal", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single container. Environment VALUES are redacted by default — every variable reads \"set\", so you can see which are configured without the response carrying secrets. Pass ?reveal=true when you need the values themselves.", "tags": [ "container" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } }, "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "env": { "additionalProperties": true, "description": "Variables to set, name → value. A null value deletes that variable. MYAPI_KEY is set by the platform and is refused here.", "type": "object" }, "health_check": { "description": "Startup probe path, for example \"/livez\". Send \"\" to clear it. Omit to keep the current one. NOT /healthz — that path is answered before it reaches your container, so a probe against it passes even when your app is down, and it is refused. Settable here as well as at creation: it used to be create-only, which made changing it a delete-and-recreate that lost the URL, the scoped key and the custom domain.", "type": "string" } }, "type": "object" } } }, "description": "Environment and runtime changes", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "ENV_REQUIRED", "INVALID_HEALTH_CHECK", "INVALID_ENV_NAME", "RESERVED_ENV_NAME", "ENV_VALUE_TOO_LARGE", "TOO_MANY_ENV_VARS", "ENV_NOT_APPLIED", "INVALID_JSON", "RATE_LIMITED", "INVALID_REQUEST", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `ENV_REQUIRED` — Send env with at least one variable to change, or health_check.; `INVALID_HEALTH_CHECK` — health_check must be a path starting with /, and cannot be /healthz.; `INVALID_ENV_NAME` — A name must be letters, digits and underscores, and cannot start with a digit.; `RESERVED_ENV_NAME` — MYAPI_KEY is set by the platform on every deploy.; `ENV_VALUE_TOO_LARGE` — One value is over 32 KB.; `TOO_MANY_ENV_VARS` — Over 100 variables.; `ENV_NOT_APPLIED` — The values were stored but the redeploy failed, so the container still runs the previous ones.; `INVALID_JSON` — The request body is not valid JSON.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Change environment variables or the startup probe on an existing container, and roll a new revision on the SAME image so they take effect. This is a merge: send only the variables you are changing, and null to delete one — everything else keeps its value. The response carries the RESULTING env, so a change needs no second call to confirm. Before this existed, editing one variable meant deleting the container and creating another, which lost the URL, the scoped key and the custom domain. The image is not rebuilt: an environment change is not a code change, and rebuilding would make a one-string edit depend on your source still building.", "tags": [ "container" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/container/orgs/{org_id}/containers/{id}/build-logs": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lines to return (default 100, max 1000).", "in": "query", "name": "tail", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Return the container's most recent source-build step logs, oldest first — shows WHY a build failed.", "tags": [ "container" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/container/orgs/{org_id}/containers/{id}/deploy": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "image": { "description": "Pre-built image ref, e.g. gcr.io/project/name:tag. Provide this OR a source build.", "type": "string" }, "promote": { "description": "Default TRUE — the new revision takes all traffic as soon as it is ready, which is the behaviour you already get. Send false to deploy without exposing it: the response carries a revision_url addressing that build directly, so you can test it before customers reach it, then POST .../promote. The currently serving revision is untouched until you do. Ignored on the FIRST deploy of a container: there is nothing already serving to hold traffic, so withholding it would leave the container answering nothing at all. The promoted field in the response says what actually happened.", "type": "boolean" }, "smoke": { "description": "An assertion checked against the new revision BEFORE it takes traffic. Passing one means verify-then-promote: the revision is deployed without traffic, checked, and promoted only if the check holds. A failure leaves the previous revision serving.", "properties": { "contains": { "description": "Substring the response body must contain. This is the field that distinguishes a real build from a placeholder that returns 200.", "type": "string" }, "method": { "description": "Request method (default GET)", "enum": [ "GET", "HEAD" ], "type": "string" }, "path": { "description": "Path to request (default /).", "type": "string" }, "status": { "description": "Expected HTTP status. Omit for any 2xx.", "type": "integer" } }, "type": "object" }, "source_ref": { "description": "A build context uploaded directly to storage via POST .../source-upload. Use this instead of a multipart source when the context is larger than 30MB.", "type": "string" } }, "type": "object" } }, "multipart/form-data": { "schema": { "properties": { "image": { "description": "Pre-built image ref, as an alternative to source. Send one or the other, not both.", "type": "string" }, "promote": { "description": "\"false\" deploys the build WITHOUT giving it traffic — the response carries a revision_url to test it at, and the currently serving revision keeps serving. Default \"true\". Ignored on a container's first deploy, since there is nothing already serving to hold traffic.", "type": "string" }, "smoke": { "description": "An assertion checked against the new revision BEFORE it takes traffic, as a JSON object in this field: {\"path\":\"/\",\"status\":200,\"contains\":\"\u003ctitle\u003e\"}. The revision is promoted only if it holds. On a source build the result lands on the container — poll GET .../containers/{id} — because the deploy has already returned.", "type": "string" }, "source": { "description": "Build context as a gzipped tar, max 30MB. The whole archive is uploaded, so exclude what the image does not need: dependency directories (node_modules, vendor, target), .git, and build output. A .dockerignore is honoured during the BUILD but not during the upload, so it does not shrink the archive — leave those files out of the tar itself.", "format": "binary", "type": "string" } }, "required": [ "source" ], "type": "object" } } }, "description": "Deploy a pre-built image, or a source build context Deploy from source", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_SMOKE", "SMOKE_FAILED", "SMOKE_UNREACHABLE", "SOURCE_TOO_LARGE", "SOURCE_REF_UNKNOWN", "SOURCE_REF_EXPIRED", "SOURCE_NOT_UPLOADED", "PROMOTE_FAILED", "DEPLOY_FAILED", "CONTAINER_DELETED", "INVALID_SMOKE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_SMOKE` — The smoke assertion is not usable — see the message. An assertion with neither a status nor a contains is refused, because it would pass for any running container.; `SMOKE_FAILED` — The smoke assertion did not hold. The deploy was NOT promoted and the previous revision is still serving.; `SMOKE_UNREACHABLE` — The new revision had no address to test against, so the check could not run. The deploy was NOT promoted.; `SOURCE_TOO_LARGE` — The build context is over 30MB. Exclude dependency directories and build output; the upload happens before .dockerignore is read. For a context that is genuinely larger, use POST .../source-upload and deploy with source_ref.; `SOURCE_REF_UNKNOWN` — That source_ref does not belong to this container.; `SOURCE_REF_EXPIRED` — That upload slot has expired. Request a new one and upload again.; `SOURCE_NOT_UPLOADED` — No build context was uploaded to that source_ref. Finish the PUT before deploying.; `PROMOTE_FAILED` — The smoke assertion passed but traffic could not be moved. The previous revision is still serving; retry with POST .../promote.; `DEPLOY_FAILED` — The runtime refused the deploy. The body carries retryable: true when the cause was on our side and deploying again is the right move, false when the container itself must change first.; `CONTAINER_DELETED` — The container was deleted while this deploy ran. The runtime it created is being torn down; nothing is serving.; `INVALID_SMOKE` — The smoke assertion is not usable — see the message. An assertion with neither a status nor a contains is refused, because it would pass for any running container.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Deploy a container, in one of two shapes: an already-built `image` ref as JSON, or a `source` build context as multipart/form-data. A source build runs server-side and asynchronously — poll GET .../containers/{id} for the outcome, and expect it to take a few minutes rather than seconds. Set `promote:false` to deploy WITHOUT giving the new revision traffic: the response carries a revision_url addressing that build directly, so you can test it before customers reach it, and the currently serving revision is untouched until you POST .../promote. The revision_url is UNLISTED, NOT authenticated: anyone who has it can reach the revision, so do not treat it as private — an application whose configuration must not be exposed should not be deployed as a public service at all. Pass `smoke` to assert the build works BEFORE it takes traffic: the revision deploys without traffic, the assertion runs against it, and it is promoted only if the assertion holds — a failure leaves the previous revision serving. Handles service, worker and job runtime types.", "tags": [ "container" ], "x-safety": { "denylist": false, "disclosure": "live_site_change", "kind": "mutate", "proof": [ "http" ], "reversible": false, "risk": "high" } } }, "/container/orgs/{org_id}/containers/{id}/domain": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Remove the container's custom domain (tears down the CNAME + routing rule).", "tags": [ "container" ], "x-safety": { "denylist": false, "disclosure": "live_site_change", "kind": "mutate", "reversible": false, "risk": "high" } }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "domain": { "description": "Hostname to route to the container (e.g. app.synthesisdaily.com). Must be inside a domain the org registered through MyAPI.", "type": "string" } }, "required": [ "domain" ], "type": "object" } } }, "description": "Custom domain payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Route a custom domain to the container. Creates a proxied CNAME to the container's origin host plus a routing rule that rewrites the Host/SNI so the origin accepts the request — no domain mapping or third-party domain verification needed. The domain must sit inside a MyAPI-managed zone the org owns.", "tags": [ "container" ], "x-safety": { "denylist": false, "disclosure": "live_site_change", "kind": "mutate", "proof": [ "dns", "http" ], "reverse": "DELETE /container/orgs/{org_id}/containers/{id}/domain", "reversible": true, "risk": "high" } } }, "/container/orgs/{org_id}/containers/{id}/logs": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lines to return (default 100, max 1000).", "in": "query", "name": "tail", "required": false, "schema": { "type": "integer" } }, { "description": "`app` (default) returns the container's own stdout/stderr. `all` also includes platform audit records, which are multi-kilobyte JSON blobs on the same stream and will consume the tail budget.", "in": "query", "name": "scope", "required": false, "schema": { "enum": [ "app", "all" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Return the container's recent runtime logs, newest first. Returns the container's own stdout/stderr only; platform audit records are excluded unless asked for.", "tags": [ "container" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/container/orgs/{org_id}/containers/{id}/promote": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "revision": { "description": "Revision to serve. Omit to roll back to the previous ready revision.", "type": "string" } }, "type": "object" } } }, "description": "Promotion target", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_A_SERVICE", "REVISION_NOT_FOUND", "REVISION_NOT_READY", "NO_ROLLBACK_TARGET", "PROMOTE_FAILED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_A_SERVICE` — A job has no traffic to shift. Trigger it instead.; `REVISION_NOT_FOUND` — No such revision for this container. List revisions to see what is available.; `REVISION_NOT_READY` — That revision never became ready, so it cannot take traffic. Traffic was NOT moved.; `NO_ROLLBACK_TARGET` — No earlier revision is available to roll back to. Name one explicitly.; `PROMOTE_FAILED` — The traffic shift did not complete. Traffic was NOT moved.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Move all traffic to one revision. This is a traffic shift only — no build, no new revision — so it completes in seconds. Omit `revision` to roll back to the previous ready revision. The same call serves promote and rollback; only the target differs.", "tags": [ "container" ], "x-safety": { "denylist": false, "disclosure": "live_site_change", "kind": "mutate", "proof": [ "http" ], "reverse": "POST /container/orgs/{org_id}/containers/{id}/promote", "reversible": true, "risk": "high" } } }, "/container/orgs/{org_id}/containers/{id}/revisions": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Revision list", "properties": { "revisions": { "description": "Revisions, newest first", "items": { "description": "Revision", "properties": { "created_at": { "description": "RFC3339 creation time.", "type": "string" }, "ready": { "description": "Whether the revision started successfully. Only a ready revision can take traffic.", "type": "boolean" }, "revision": { "description": "Revision name. Pass this to promote.", "type": "string" }, "serving": { "description": "True when the revision takes any traffic.", "type": "boolean" }, "traffic_percent": { "description": "Percent of traffic this revision currently serves.", "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_A_SERVICE", "REVISIONS_UNAVAILABLE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_A_SERVICE` — A job has no traffic to split, so it has no revisions.; `REVISIONS_UNAVAILABLE` — The runtime could not be reached. Try again in a moment.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List the container's revisions, newest first, with the traffic each one takes. Read from the runtime, so it shows what actually exists — older revisions are eventually removed and cannot be promoted.", "tags": [ "container" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/container/orgs/{org_id}/containers/{id}/run": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_A_JOB", "NOT_DEPLOYED", "RUNTIME_UNAVAILABLE", "RUN_FAILED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_A_JOB` — Only a type=job container can be run on demand.; `NOT_DEPLOYED` — Deploy the job before running it.; `RUNTIME_UNAVAILABLE` — The container runtime is not configured on this deployment.; `RUN_FAILED` — The run did not start. Nothing was run.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Run a type=job container on demand (not just on its cron). Returns the started execution's name; the run proceeds asynchronously — poll .../runs for its status. 422 if the container is not a job; 409 if it has not been deployed yet.", "tags": [ "container" ], "x-safety": { "denylist": false, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/container/orgs/{org_id}/containers/{id}/runs": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Executions to return (1..100, default 50).", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_A_JOB", "RUNTIME_UNAVAILABLE", "RUNS_FAILED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_A_JOB` — Only a type=job container can list runs.; `RUNTIME_UNAVAILABLE` — The container runtime is not configured on this deployment.; `RUNS_FAILED` — The run history could not be read.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List a job container's recent executions (run history) with exit counts and timing, newest first. 422 if the container is not a job.", "tags": [ "container" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/container/orgs/{org_id}/containers/{id}/scopes": { "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "scopes": { "description": "Slot names the container may call, for example [\"crm\",\"email\"]. This REPLACES the current list; include the slots you want to keep.", "items": { "type": "string" }, "type": "array" } }, "required": [ "scopes" ], "type": "object" } } }, "description": "New slot list — replaces the current one", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SCOPES_REQUIRED", "INVALID_SCOPES", "SCOPE_FORBIDDEN", "SCOPES_NOT_APPLIED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SCOPES_REQUIRED` — scopes named no slots. Nothing was changed.; `INVALID_SCOPES` — scopes named a slot that does not exist. Nothing was changed.; `SCOPE_FORBIDDEN` — The requested scopes are wider than the key making the change. Nothing was changed.; `SCOPES_NOT_APPLIED` — The scopes were stored but the redeploy failed, so the container still runs with the previous key.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Change which slots a container may call, without recreating it. The container id, URL and custom domain are unchanged. The scoped key is replaced: a deployed container is redeployed on the SAME image with the new key as MYAPI_KEY, so the change takes effect at once — a narrowing that left the old key alive would narrow nothing. Scopes can never exceed the grants of the key making the change. GET the container to see its current scopes.", "tags": [ "container" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/container/orgs/{org_id}/containers/{id}/source-upload": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Upload slot", "properties": { "expires_at": { "description": "RFC3339. After this the slot is refused and a new one is needed.", "type": "string" }, "method": { "description": "HTTP method to use for the upload.", "type": "string" }, "source_ref": { "description": "Pass this to deploy as source_ref once the upload finishes.", "type": "string" }, "upload_url": { "description": "PUT the gzipped tar here, with Content-Type: application/gzip. No credentials required — the URL carries its own authorisation.", "type": "string" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "UPLOAD_UNAVAILABLE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `UPLOAD_UNAVAILABLE` — An upload slot could not be opened. Try again in a moment.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Open a slot to upload a build context larger than the request body limit. Returns an upload_url to PUT the gzipped tar to directly — the bytes do not pass through this API, so the 30MB body cap does not apply — and a source_ref to pass to deploy. The slot expires after 2 hours.", "tags": [ "container" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/crm/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of crm: method, path, auth, params, error codes — public, no auth", "tags": [ "crm" ] } }, "/crm/orgs/{org_id}/companies": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Companies per page (1..500, default 50). Values outside the range fall back to 50.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Companies to skip. Use with `total`/`has_more` to page; both describe the whole match set, not the page.", "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "description": "Exact company-domain match.", "in": "query", "name": "domain", "required": false, "schema": { "type": "string" } }, { "description": "Match companies by a contact email on the company.", "in": "query", "name": "email", "required": false, "schema": { "type": "string" } }, { "description": "Restrict to a single company by id.", "in": "query", "name": "company_id", "required": false, "schema": { "type": "string" } }, { "description": "Comma-separated list; matches any of them.", "in": "query", "name": "lifecycle_stage", "required": false, "schema": { "type": "string" } }, { "description": "Comma-separated list; matches any of them.", "in": "query", "name": "source", "required": false, "schema": { "type": "string" } }, { "description": "Only companies last engaged at least this many days ago.", "in": "query", "name": "min_last_engagement_days", "required": false, "schema": { "type": "integer" } }, { "description": "Only companies last engaged at most this many days ago.", "in": "query", "name": "max_last_engagement_days", "required": false, "schema": { "type": "integer" } }, { "description": "Pass `true` to include soft-deleted companies.", "in": "query", "name": "include_deleted", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List companies. Paginate with limit + offset; the response carries the true match count in `total` and `has_more`. For richer filters use POST .../search.", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "custom": { "description": "Arbitrary JSON object (≤ 64 KB).", "type": "string" }, "domain": { "description": "Domain — natural key. Lowercased.", "type": "string" }, "lifecycle_stage": { "description": "Stage", "enum": [ "cold", "warm", "qualified", "customer", "churned" ], "type": "string" }, "name": { "description": "Display name.", "type": "string" }, "source": { "description": "Where this company came from", "enum": [ "goldfox", "email", "pixel", "webhook", "manual" ], "type": "string" } }, "type": "object" } } }, "description": "Company create payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create or upsert a company by domain.", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /crm/orgs/{org_id}/companies/{id}", "reversible": true, "risk": "low" } } }, "/crm/orgs/{org_id}/companies/promote": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "goldfox_company_id": { "description": "Goldfox company id — usually the domain.", "type": "string" } }, "required": [ "goldfox_company_id" ], "type": "object" } } }, "description": "Promote company payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Promote a Goldfox company into the org's CRM. The Goldfox company id IS its domain. Returns the existing company if domain already matches.", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/crm/orgs/{org_id}/companies/search": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "domain": { "description": "Exact domain match", "type": "string" }, "include_deleted": { "description": "Include soft-deleted companies", "type": "boolean" }, "lifecycle_stage": { "description": "Match any of these stages", "items": { "description": "Lifecycle stage", "enum": [ "cold", "warm", "qualified", "customer", "churned" ], "type": "string" }, "type": "array" }, "limit": { "description": "Max results, 1–500 (default 50)", "type": "integer" }, "max_last_engagement_days": { "description": "Only companies engaged at most this many days ago", "type": "integer" }, "min_last_engagement_days": { "description": "Only companies engaged at least this many days ago", "type": "integer" }, "offset": { "description": "Results to skip, for paging (default 0). The response carries total and has_more, so page until has_more is false.", "type": "integer" }, "source": { "description": "Match any of these sources", "items": { "description": "Source name", "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Filters — all optional; an empty body returns the most recently engaged companies", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Search companies. Filters: lifecycle_stage[], source[], domain, include_deleted.", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/crm/orgs/{org_id}/companies/{id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Soft delete company.", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "POST /crm/orgs/{org_id}/companies/{id}/restore", "reversible": true, "risk": "low" } }, "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a company. Includes `goldfox_company` enrichment when goldfox_company_id is set (deferred — null in v1).", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } }, "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "custom": { "additionalProperties": true, "description": "Arbitrary custom fields", "type": "object" }, "deleted_at": { "description": "Set to null to restore a soft-deleted company", "type": "string" }, "domain": { "description": "Company domain", "type": "string" }, "lifecycle_stage": { "description": "Lifecycle stage", "enum": [ "cold", "warm", "qualified", "customer", "churned" ], "type": "string" }, "name": { "description": "Company name", "type": "string" } }, "type": "object" } } }, "description": "Fields to change — omitted fields are left untouched", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Partial update for company.", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/crm/orgs/{org_id}/companies/{id}/restore": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Restore a soft-deleted company. Clears deleted_at. Returns 404 if the company does not exist OR is not currently soft-deleted.", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/crm/orgs/{org_id}/contacts": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Contacts per page (1..500, default 50). Values outside the range fall back to 50.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Contacts to skip. Use with `total`/`has_more` to page; both describe the whole match set, not the page.", "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "description": "Exact email match.", "in": "query", "name": "email", "required": false, "schema": { "type": "string" } }, { "description": "Exact email-domain match.", "in": "query", "name": "domain", "required": false, "schema": { "type": "string" } }, { "description": "Only contacts belonging to this company.", "in": "query", "name": "company_id", "required": false, "schema": { "type": "string" } }, { "description": "Comma-separated list; matches any of them.", "in": "query", "name": "lifecycle_stage", "required": false, "schema": { "type": "string" } }, { "description": "Comma-separated list; matches any of them.", "in": "query", "name": "source", "required": false, "schema": { "type": "string" } }, { "description": "Only contacts last engaged at least this many days ago.", "in": "query", "name": "min_last_engagement_days", "required": false, "schema": { "type": "integer" } }, { "description": "Only contacts last engaged at most this many days ago.", "in": "query", "name": "max_last_engagement_days", "required": false, "schema": { "type": "integer" } }, { "description": "Pass `true` to include soft-deleted contacts.", "in": "query", "name": "include_deleted", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List contacts. Paginate with limit + offset; the response carries the true match count in `total` and `has_more`. For richer filters use POST .../search.", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "company_id": { "description": "Override the auto-linked company. UUID of an existing crm_companies row in this org.", "type": "string" }, "custom": { "description": "Arbitrary JSON object (≤ 64 KB). No schema validation.", "type": "string" }, "email": { "description": "Email address — natural key. Lowercased on write. Optional but recommended.", "type": "string" }, "first_name": { "description": "First name (optional).", "type": "string" }, "last_name": { "description": "Last name (optional).", "type": "string" }, "lifecycle_stage": { "description": "Stage", "enum": [ "cold", "warm", "qualified", "customer", "churned" ], "type": "string" }, "source": { "description": "Where this contact came from", "enum": [ "goldfox", "email", "pixel", "webhook", "manual" ], "type": "string" } }, "type": "object" } } }, "description": "Contact create payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create or upsert a contact by email. If a contact with the supplied email exists, returns it unchanged (PATCH to merge fields). Emits a `created` event on first write. Auto-links to a crm_companies row by email domain.", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /crm/orgs/{org_id}/contacts/{id}", "reversible": true, "risk": "low" } } }, "/crm/orgs/{org_id}/contacts/import": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "description": "CSV with a header row; `email` required, `first_name`/`last_name` optional.", "format": "binary", "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "description": "The CSV file", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "FILE_REQUIRED", "CSV_EMPTY", "CSV_UNREADABLE", "EMAIL_COLUMN_REQUIRED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `FILE_REQUIRED` — Send the CSV as multipart/form-data with a `file` part.; `CSV_EMPTY` — The file has no rows.; `CSV_UNREADABLE` — The body could not be read as CSV.; `EMAIL_COLUMN_REQUIRED` — No `email` column in the header row.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Import contacts from CSV. Header row required; `email` is the only required column, `first_name`, `last_name` are used when present, and unknown columns are ignored. An address already in CRM is matched, not duplicated or overwritten — a spreadsheet is not more authoritative than the record somebody has been working. Returns per-row reasons for anything skipped.", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/crm/orgs/{org_id}/contacts/promote": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "goldfox_person_id": { "description": "Goldfox person id (e.g. p_\u003cbase64\u003e.4 from GET /people/...).", "type": "string" } }, "required": [ "goldfox_person_id" ], "type": "object" } } }, "description": "Promote payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Promote a Goldfox person into the org's CRM. Looks up the person in Goldfox, copies email + name into a new contact (source='goldfox', stage='cold'), auto-links/creates the company by domain. Returns the existing contact if one with the same email already lives in this org (backfilling the goldfox_person_id link). Emits `created` + `promoted` events on first run; idempotent thereafter.", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/crm/orgs/{org_id}/contacts/promote-audience": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "audience_id": { "description": "A saved audience from GET /audience/orgs/{org_id}/audiences. Must be a people audience.", "type": "string" }, "limit": { "description": "People per call (1..500, default 500).", "type": "integer" }, "offset": { "description": "Where to resume; use next_offset from the previous reply.", "type": "integer" } }, "required": [ "audience_id" ], "type": "object" } } }, "description": "Which audience, and how much of it", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "AUDIENCE_ID_REQUIRED", "AUDIENCE_NOT_FOUND", "AUDIENCE_NOT_PEOPLE", "GOLDFOX_UNAVAILABLE", "AUDIENCE_QUERY_FAILED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `AUDIENCE_ID_REQUIRED` — audience_id names a saved audience.; `AUDIENCE_NOT_FOUND` — No audience with that id in this org.; `AUDIENCE_NOT_PEOPLE` — Only a people audience can become contacts.; `GOLDFOX_UNAVAILABLE` — The lead database is not reachable right now.; `AUDIENCE_QUERY_FAILED` — The audience could not be read.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Promote a saved people-audience into CRM contacts in one call, instead of looping promote per id. Idempotent: a person already promoted is matched, not duplicated. Returns counts and a next_offset — promote a large audience by calling again.", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/crm/orgs/{org_id}/contacts/search": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "company_id": { "description": "Restrict to a single company.", "type": "string" }, "email": { "description": "Exact-match email lookup.", "type": "string" }, "include_deleted": { "description": "0/1 — include soft-deleted contacts (default 0).", "type": "integer" }, "lifecycle_stage": { "description": "Stages to include (any-of)", "items": { "description": "stage", "type": "string" }, "type": "array" }, "limit": { "description": "Max rows (default 50, max 500).", "type": "integer" }, "max_last_engagement_days": { "description": "Match contacts last engaged \u003e N days ago (re-engagement).", "type": "integer" }, "min_last_engagement_days": { "description": "Match contacts engaged within N days.", "type": "integer" }, "offset": { "description": "Rows to skip, for paging (default 0). The response carries total and has_more, so page until has_more is false.", "type": "integer" }, "source": { "description": "Sources to include (any-of)", "items": { "description": "source", "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Search filter", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Search contacts. Filters: lifecycle_stage[], source[], min/max_last_engagement_days, email, company_id, include_deleted. Returns newest-engagement-first. Paginate with limit + offset; `total` is the true match count and `has_more` flags a truncated page.", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/crm/orgs/{org_id}/contacts/{id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Soft delete. Sets deleted_at; events are retained. Restore via POST .../restore or PATCH { \"deleted_at\": null }.", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "POST /crm/orgs/{org_id}/contacts/{id}/restore", "reversible": true, "risk": "low" } }, "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a contact. When goldfox_person_id is set, the response includes a live `goldfox_person` enrichment field (deferred — null in v1 until the BQ get-by-id helper lands).", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } }, "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "company_id": { "description": "Replace the linked company.", "type": "string" }, "custom": { "description": "Replace the custom JSONB object.", "type": "string" }, "email": { "description": "Update email (optional).", "type": "string" }, "first_name": { "description": "Update first name.", "type": "string" }, "last_name": { "description": "Update last name.", "type": "string" }, "lifecycle_stage": { "description": "Stage", "enum": [ "cold", "warm", "qualified", "customer", "churned" ], "type": "string" } }, "type": "object" } } }, "description": "Contact patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "EMAIL_IN_USE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `EMAIL_IN_USE` — The email is already used by another contact in this org. The contact was NOT changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Partial update. Changing lifecycle_stage emits a `stage_changed` event with {from,to}. PATCH { \"deleted_at\": null } restores a soft-deleted contact.", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/crm/orgs/{org_id}/contacts/{id}/events": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Events per page (1..200, default 50). Out-of-range values are rejected with 400.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Keyset cursor from the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Filter to one event kind.", "in": "query", "name": "kind", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Contact event timeline, newest first. Keyset-paginated: the cursor is the id of the last event from the previous page.", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/crm/orgs/{org_id}/contacts/{id}/restore": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Restore a soft-deleted contact. Clears deleted_at. Returns 404 if the contact does not exist OR is not currently soft-deleted.", "tags": [ "crm" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/database/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of database: method, path, auth, params, error codes — public, no auth", "tags": [ "database" ] } }, "/database/orgs/{org_id}/namespaces": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List KV namespaces in the org. Each entry includes an approximate key_count.", "tags": [ "database" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "Unique namespace name (^[a-z0-9][a-z0-9_-]{0,62}$).", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "description": "Namespace create payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NAMESPACE_EXISTS", "NAMESPACE_NAME_INVALID", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NAMESPACE_EXISTS` — A namespace with that name already exists in this org.; `NAMESPACE_NAME_INVALID` — The namespace name is not usable — see the message. Nothing was created.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a KV namespace. Names match ^[a-z0-9][a-z0-9_-]{0,62}$; the prefix '__myapi_' is reserved.", "tags": [ "database" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/database/orgs/{org_id}/namespaces/{ns}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "ns", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete a namespace and ALL its keys (irreversible). Returns 204.", "tags": [ "database" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } }, "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "ns", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single namespace's metadata (name, created_at, approximate key_count).", "tags": [ "database" ] } }, "/database/orgs/{org_id}/namespaces/{ns}/keys": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "ns", "required": true, "schema": { "type": "string" } }, { "description": "Only keys starting with this prefix.", "in": "query", "name": "prefix", "required": false, "schema": { "type": "string" } }, { "description": "Keys per page (1..1000, default 50). Out-of-range values are rejected with 400.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Keyset cursor from the previous page — pass meta.next_cursor verbatim (base64url), NOT a key. A malformed cursor is rejected with 400.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Pass `true` to include each key's value in the response.", "in": "query", "name": "values", "required": false, "schema": { "type": "boolean" } }, { "description": "NOT supported — this list pages by cursor. Passing offset is rejected with 400 (it was silently ignored before); use ?cursor= with the previous page's meta.next_cursor instead.", "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List keys (and optionally values) in a namespace. Query: prefix=, limit=1-1000 (default 50), cursor=, values=true|false (default false). Pagination is by cursor, not offset: pass the meta.next_cursor from the previous page as ?cursor=. `offset` is NOT supported and is rejected with 400 rather than silently ignored.", "tags": [ "database" ] } }, "/database/orgs/{org_id}/namespaces/{ns}/keys/{key}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "ns", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NAMESPACE_NOT_FOUND", "KEY_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NAMESPACE_NOT_FOUND` — No namespace with that name in this org.; `KEY_NOT_FOUND` — No key with that name in this namespace. Nothing was deleted.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete a key. Optional 'If-Match: \u003cetag\u003e' for CAS-protected delete.", "tags": [ "database" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } }, "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "ns", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NAMESPACE_NOT_FOUND", "KEY_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NAMESPACE_NOT_FOUND` — No namespace with that name in this org.; `KEY_NOT_FOUND` — No key with that name in this namespace.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a key's value, etag, and updated_at. 404 if the key or namespace is missing.", "tags": [ "database" ] }, "put": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "ns", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "value": { "description": "Any valid JSON (object, array, scalar). ≤ 256 KB serialized.", "type": "string" } }, "required": [ "value" ], "type": "object" } } }, "description": "Key-value upsert payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "ETAG_MISMATCH", "VALUE_TOO_LARGE", "KEY_TOO_LARGE", "NAMESPACE_NOT_FOUND", "VALUE_NOT_JSON", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `ETAG_MISMATCH` — The key changed since the etag you sent, so the write was REFUSED and nothing was stored. Read the key again, re-apply your change to the new value, and retry with the new etag. This is the compare-and-swap that makes concurrent writes safe — retrying without re-reading overwrites whoever won.; `VALUE_TOO_LARGE` — The value is over the per-key size limit. Nothing was stored.; `KEY_TOO_LARGE` — The key name is over the length limit. Nothing was stored.; `NAMESPACE_NOT_FOUND` — No namespace with that name in this org. Create it first.; `VALUE_NOT_JSON` — The value is not valid JSON. Nothing was stored.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Set a key's value. Optional 'If-Match: \u003cetag\u003e' header for CAS — returns 412 ETAG_MISMATCH if the stored etag differs. Value must be valid JSON ≤ 256 KB; binary belongs in /storage.", "tags": [ "database" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/domain/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of domain: method, path, auth, params, error codes — public, no auth", "tags": [ "domain" ] } }, "/domain/orgs/{org_id}/check/available/{domain}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "domain", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_DOMAIN", "TLD_NOT_SUPPORTED", "DOMAIN_UNAVAILABLE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_DOMAIN` — That is not a usable domain name.; `TLD_NOT_SUPPORTED` — That top-level domain cannot be registered here. If you already own it elsewhere, bring it with POST /domain/orgs/{org_id}/import — that needs no registrar credentials.; `DOMAIN_UNAVAILABLE` — The registry could not be asked whether this domain is free. Nothing was reserved.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Check domain availability + at-cost price. Currently behind a feature flag — availability and pricing come from the registrar we hold the domain with.", "tags": [ "domain" ] } }, "/domain/orgs/{org_id}/import": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "domain": { "description": "Fully-qualified domain you already own (e.g. \"example.com\")", "type": "string" } }, "required": [ "domain" ], "type": "object" } } }, "description": "Domain to import", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "DOMAIN_TAKEN", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `DOMAIN_TAKEN` — The domain is already tracked by another account. Nothing was imported.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Import an existing domain (no registrar charge)", "tags": [ "domain" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/domain/orgs/{org_id}/list": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Restrict the listing to a subset of domains.", "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List domains belonging to the org.", "tags": [ "domain" ] } }, "/domain/orgs/{org_id}/register": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Retry-safety token. Repeating the same key replays the original response instead of registering (and charging) again. Send one on every registration — the operation is paid and cannot be undone.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "domain": { "description": "Domain to register, e.g. \"coachname.com\"", "type": "string" }, "registrant": { "description": "WHOIS registrant contact. The customer's real details — NOT MyAPI's. Optional today, required after the registrar cutover.", "properties": { "city": { "description": "City", "type": "string" }, "country_code": { "description": "ISO 3166-1 alpha-2 country code (e.g. \"US\")", "type": "string" }, "email": { "description": "Contact email", "type": "string" }, "name": { "description": "Full legal name", "type": "string" }, "organization": { "description": "Organization name (optional)", "type": "string" }, "phone": { "description": "E.164 phone, e.g. +1.5555551234", "type": "string" }, "postal_code": { "description": "Postal/ZIP code", "type": "string" }, "state": { "description": "State/Province (required for US/CA)", "type": "string" }, "street": { "description": "Street address", "type": "string" } }, "type": "object" }, "years": { "description": "Registration period in years (default 1)", "type": "integer" } }, "required": [ "domain" ], "type": "object" } } }, "description": "Domain registration payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "REGISTRATION_IN_PROGRESS", "REGISTRATION_UNRESOLVED", "REGISTRATION_RECORD_FAILED", "DOMAIN_ALREADY_OWNED", "RATE_LIMITED", "INSUFFICIENT_FUNDS", "DOMAIN_TAKEN", "INVALID_REGISTRANT", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `REGISTRATION_IN_PROGRESS` — A registration for this domain is already running. Wait for it to finish, then read the domain from the list endpoint.; `REGISTRATION_UNRESOLVED` — A previous registration did not finish and we cannot yet confirm whether it completed. Retry shortly; the domain was NOT registered twice.; `REGISTRATION_RECORD_FAILED` — The domain was registered but recording it failed. Do not retry payment; read the domain from the list endpoint.; `DOMAIN_ALREADY_OWNED` — This account already holds the domain.; `RATE_LIMITED` — Too many registration attempts. Wait a minute and retry with an Idempotency-Key.; `INSUFFICIENT_FUNDS` — The account balance does not cover the registration. Promotional credits cannot be used for domains.; `DOMAIN_TAKEN` — The domain is already registered to another account. Pick another, or import it if you own it.; `INVALID_REGISTRANT` — The registrant contact is not usable — see the message. Nothing was registered.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Register a domain. `registrant` carries the customer's real WHOIS contact details — the customer is the registrant of record, not MyAPI. It is OPTIONAL today and will become REQUIRED; send it now and the change will not break you. ICANN requires name, email, phone, street, city, postal_code, country_code (ISO 3166-1 alpha-2), plus state for US/CA. DNS hosting is provisioned automatically as part of registration.", "tags": [ "domain" ], "x-safety": { "denylist": true, "disclosure": "money", "kind": "mutate", "proof": [ "dns" ], "reversible": false, "risk": "high" } } }, "/domain/orgs/{org_id}/{domain}/assign": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "domain", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "funnel_id": { "description": "Which funnel the domain routes to. Required when the org has more than one funnel; otherwise defaults to the most recent funnel.", "type": "string" }, "include_www": { "description": "Also route the www subdomain (default true)", "type": "boolean" }, "org_id": { "description": "Org to assign the domain to", "type": "string" } }, "type": "object" } } }, "description": "Assignment target", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "DOMAIN_NOT_FOUND", "DOMAIN_NOT_VERIFIED", "NOT_ON_OUR_DNS", "ORG_NOT_FOUND", "ORG_REQUIRED", "FUNNEL_NOT_IN_ORG", "FUNNEL_ID_REQUIRED", "DOMAIN_IN_USE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `DOMAIN_NOT_FOUND` — No such domain in this org.; `DOMAIN_NOT_VERIFIED` — The domain is not verified yet, so nothing was bound to it.; `NOT_ON_OUR_DNS` — The domain's nameservers do not point here.; `ORG_NOT_FOUND` — No such org.; `ORG_REQUIRED` — You sent funnel_id but no org_id — org_id is required to assign. To unassign, send org_id: null with no funnel_id.; `FUNNEL_NOT_IN_ORG` — The funnel belongs to a different org. Use a funnel from this org.; `FUNNEL_ID_REQUIRED` — The org has more than one funnel and no funnel_id was sent. The domain was NOT changed. Send funnel_id; the body lists the funnels.; `DOMAIN_IN_USE` — The domain is assigned to another resource. Unassign it first — see the message.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Point a domain — or a SUBDOMAIN of one you own — at an org's funnel. The {domain} path segment may be the registrable domain (example.com), which also binds www unless include_www is false, or any subdomain of a domain in this account (app.example.com), which binds only itself and leaves the parent and every other subdomain untouched. The parent domain must already be in this account: register it, or bring one you own with POST /domain/orgs/{org_id}/import. Do NOT CNAME a subdomain at a funnel hostname yourself — the edge cannot reach an origin that is itself an edge zone, and the result is a 522.", "tags": [ "domain" ], "x-safety": { "denylist": false, "disclosure": "live_site_change", "kind": "mutate", "proof": [ "dns", "http" ], "reversible": false, "risk": "high" } } }, "/domain/orgs/{org_id}/{domain}/email-infra": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "domain", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "subdomain": { "description": "DNS label (1-63 chars, alphanumeric + hyphens). Defaults to 'mail'.", "type": "string" } }, "type": "object" } } }, "description": "Email infra opt-in payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_SUBDOMAIN", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_SUBDOMAIN` — The subdomain is not usable — see the message. Nothing was set up.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Opt in to MyAPI-managed email on a subdomain (apex is never touched). Sets up a sending identity on \u003csubdomain\u003e.\u003cdomain\u003e and writes the DKIM, SPF and DMARC records there. Default subdomain is 'mail'.", "tags": [ "domain" ], "x-safety": { "denylist": false, "kind": "mutate", "proof": [ "dns" ], "reversible": false, "risk": "high" } } }, "/domain/orgs/{org_id}/{domain}/records": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "domain", "required": true, "schema": { "type": "string" } }, { "description": "Filter by DNS record type (A, AAAA, CNAME, TXT, MX, ...). Case-insensitive.", "in": "query", "name": "type", "required": false, "schema": { "type": "string" } }, { "description": "Rows per page (1..500, default 50). Out-of-range values are rejected with 400 rather than clamped.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Keyset cursor — pass the previous page's meta.next_cursor. Absent on the last page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "DNS_UNAVAILABLE", "DNS_ZONE_NOT_FOUND", "DNS_ZONE_UNAVAILABLE", "DOMAIN_NOT_FOUND", "FORBIDDEN", "INVALID_RECORD_TYPE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `DNS_UNAVAILABLE` — The DNS service could not be reached. Nothing was changed; retry in a moment.; `DNS_ZONE_NOT_FOUND` — This domain has no DNS zone yet. It is created during provisioning — check GET .../status.; `DNS_ZONE_UNAVAILABLE` — The DNS zone exists but could not be read or written. Nothing was changed.; `DOMAIN_NOT_FOUND` — No such domain in this org. List domains to see what is available.; `FORBIDDEN` — This domain belongs to another org.; `INVALID_RECORD_TYPE` — The record type is not supported — see the message for the accepted set.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List DNS records for the domain.", "tags": [ "domain" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "domain", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "content": { "description": "Record-type-specific value. A = IPv4 dotted-quad. AAAA = IPv6. CNAME = hostname. MX = mail server hostname. TXT = arbitrary string.", "type": "string" }, "name": { "description": "FQDN, host-only (e.g. 'mail'), or '@' / empty for apex. Backend normalizes to FQDN.", "type": "string" }, "priority": { "description": "MX priority (required when type=MX, ignored otherwise).", "type": "integer" }, "proxied": { "description": "0/1 — serve the record through the edge proxy instead of plain DNS. Only for A/AAAA/CNAME. Default 0 (DNS-only).", "type": "integer" }, "ttl": { "description": "Seconds. 1 selects an automatic TTL. Otherwise 60–86400.", "type": "integer" }, "type": { "description": "Record type", "enum": [ "A", "AAAA", "CNAME", "MX", "TXT" ], "type": "string" } }, "required": [ "type", "name", "content" ], "type": "object" } } }, "description": "DNS record creation payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "DNS_UNAVAILABLE", "DNS_ZONE_NOT_FOUND", "DNS_ZONE_UNAVAILABLE", "DOMAIN_NOT_FOUND", "FORBIDDEN", "INVALID_RECORD_TYPE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `DNS_UNAVAILABLE` — The DNS service could not be reached. Nothing was changed; retry in a moment.; `DNS_ZONE_NOT_FOUND` — This domain has no DNS zone yet. It is created during provisioning — check GET .../status.; `DNS_ZONE_UNAVAILABLE` — The DNS zone exists but could not be read or written. Nothing was changed.; `DOMAIN_NOT_FOUND` — No such domain in this org. List domains to see what is available.; `FORBIDDEN` — This domain belongs to another org.; `INVALID_RECORD_TYPE` — The record type is not supported — see the message for the accepted set. Nothing was created.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a DNS record. Supports types A, AAAA, CNAME, MX, TXT. MX requires priority. proxied applies only to A/AAAA/CNAME (default false = DNS-only).", "tags": [ "domain" ], "x-safety": { "denylist": false, "kind": "mutate", "proof": [ "dns" ], "reverse": "DELETE /domain/orgs/{org_id}/{domain}/records/{record_id}", "reversible": true, "risk": "low" } } }, "/domain/orgs/{org_id}/{domain}/records/{record_id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "domain", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "record_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "DNS_UNAVAILABLE", "DNS_ZONE_NOT_FOUND", "DNS_ZONE_UNAVAILABLE", "DOMAIN_NOT_FOUND", "FORBIDDEN", "RECORD_NOT_FOUND", "PLACEHOLDER_REQUIRED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `DNS_UNAVAILABLE` — The DNS service could not be reached. Nothing was changed; retry in a moment.; `DNS_ZONE_NOT_FOUND` — This domain has no DNS zone yet. It is created during provisioning — check GET .../status.; `DNS_ZONE_UNAVAILABLE` — The DNS zone exists but could not be read or written. Nothing was changed.; `DOMAIN_NOT_FOUND` — No such domain in this org. List domains to see what is available.; `FORBIDDEN` — This domain belongs to another org.; `RECORD_NOT_FOUND` — No DNS record with that id on this domain. Nothing was deleted.; `PLACEHOLDER_REQUIRED` — This record is how the edge serves your apex. It was NOT deleted — deleting it stops the domain resolving.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete a DNS record. Returns 204 on success, 404 if the record id isn't in this zone. The proxied apex A record is REFUSED: it is how the edge serves your apex, and deleting it stops the domain resolving — unassign the domain instead if you want it to stop serving.", "tags": [ "domain" ], "x-safety": { "denylist": false, "kind": "mutate", "proof": [ "dns" ], "reversible": false, "risk": "low" } }, "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "domain", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "record_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "DNS_UNAVAILABLE", "DNS_ZONE_NOT_FOUND", "DNS_ZONE_UNAVAILABLE", "DOMAIN_NOT_FOUND", "FORBIDDEN", "RECORD_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `DNS_UNAVAILABLE` — The DNS service could not be reached. Nothing was changed; retry in a moment.; `DNS_ZONE_NOT_FOUND` — This domain has no DNS zone yet. It is created during provisioning — check GET .../status.; `DNS_ZONE_UNAVAILABLE` — The DNS zone exists but could not be read or written. Nothing was changed.; `DOMAIN_NOT_FOUND` — No such domain in this org. List domains to see what is available.; `FORBIDDEN` — This domain belongs to another org.; `RECORD_NOT_FOUND` — No DNS record with that id on this domain.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single DNS record by its record id.", "tags": [ "domain" ] }, "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "domain", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "record_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "content": { "description": "Record value — IP, hostname, or text depending on record type", "type": "string" }, "name": { "description": "Record name (e.g. \"www\" or the full host)", "type": "string" }, "proxied": { "description": "Route through the edge proxy (A/AAAA/CNAME only)", "type": "boolean" }, "ttl": { "description": "TTL in seconds; 1 means automatic", "type": "integer" } }, "type": "object" } } }, "description": "Fields to change — omit a field to leave it untouched", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "DNS_UNAVAILABLE", "DNS_ZONE_NOT_FOUND", "DNS_ZONE_UNAVAILABLE", "DOMAIN_NOT_FOUND", "FORBIDDEN", "RECORD_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `DNS_UNAVAILABLE` — The DNS service could not be reached. Nothing was changed; retry in a moment.; `DNS_ZONE_NOT_FOUND` — This domain has no DNS zone yet. It is created during provisioning — check GET .../status.; `DNS_ZONE_UNAVAILABLE` — The DNS zone exists but could not be read or written. Nothing was changed.; `DOMAIN_NOT_FOUND` — No such domain in this org. List domains to see what is available.; `FORBIDDEN` — This domain belongs to another org.; `RECORD_NOT_FOUND` — No DNS record with that id on this domain. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Partial update of a DNS record. Type cannot change (delete + recreate instead). Only supplied fields are touched.", "tags": [ "domain" ], "x-safety": { "denylist": false, "disclosure": "live_site_change", "kind": "mutate", "proof": [ "dns" ], "reversible": false, "risk": "high" } } }, "/domain/orgs/{org_id}/{domain}/renew": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "domain", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "years": { "description": "Number of years to renew for (default 1)", "type": "integer" } }, "type": "object" } } }, "description": "Renewal term", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Renew an existing domain registration", "tags": [ "domain" ], "x-safety": { "denylist": true, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/domain/orgs/{org_id}/{domain}/retry-provisioning": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "domain", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Retry the email-infra subdomain setup after a failed attempt. Only meaningful when status='infra_error' AND email_subdomain is set. Re-runs the identity verification and the DNS writes.", "tags": [ "domain" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/domain/orgs/{org_id}/{domain}/settings": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "domain", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Read domain settings", "tags": [ "domain" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "domain", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ai_bots_protection": { "description": "Block known AI crawlers", "enum": [ "disabled", "enabled" ], "type": "string" }, "browser_check": { "description": "Browser integrity check", "enum": [ "on", "off" ], "type": "string" }, "is_robots_txt_managed": { "description": "Let MyAPI manage robots.txt for this zone", "type": "boolean" }, "purge_cache": { "description": "Purge the edge cache for this zone", "type": "boolean" }, "security_level": { "description": "Edge security level", "enum": [ "essentially_off", "medium", "high", "under_attack" ], "type": "string" } }, "type": "object" } } }, "description": "Settings to change — omitted fields are left untouched", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Update domain settings (catch-all, dns flags)", "tags": [ "domain" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/domain/orgs/{org_id}/{domain}/status": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "domain", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "DOMAIN_NOT_FOUND", "NOT_ON_OUR_DNS", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `DOMAIN_NOT_FOUND` — No such domain in this org.; `NOT_ON_OUR_DNS` — The domain's nameservers do not point here, so its records cannot be managed. Point them at the nameservers shown in the domain's status.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Return domain provisioning + email-infra status", "tags": [ "domain" ] } }, "/email/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of email: method, path, auth, params, error codes — public, no auth", "tags": [ "email" ] } }, "/email/inbox/{address}": { "get": { "parameters": [ { "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Read inbox via JMAP proxy", "tags": [ "email" ] } }, "/email/inbox/{address}/messages/{message_id}/attachments/{blob_id}": { "get": { "parameters": [ { "in": "path", "name": "address", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "message_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "blob_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MAILBOX_NOT_OWNED", "ATTACHMENT_NOT_FOUND", "UPSTREAM_ERROR", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MAILBOX_NOT_OWNED` — This mailbox does not belong to the calling account. Nothing was returned.; `ATTACHMENT_NOT_FOUND` — No attachment with that id on that message in this mailbox. Nothing was returned.; `UPSTREAM_ERROR` — The mail server would not return the attachment. Try again.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Download one attachment from a message in a mailbox you own. Returns the file itself, not JSON: Content-Type is the attachment's own type and Content-Disposition is always attachment, never inline. The ids come from the attachments array on GET /email/inbox/{address}/messages/{message_id}. Reading a message used to drop attachments entirely, so a message whose point was the attached file could not be read through the API.", "tags": [ "email" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/email/mailboxes": { "get": { "parameters": [ { "description": "Restrict to mailboxes on one domain.", "in": "query", "name": "domain", "required": false, "schema": { "type": "string" } }, { "description": "`unassigned` returns only mailboxes not yet attached to a user.", "in": "query", "name": "filter", "required": false, "schema": { "enum": [ "unassigned" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List mailboxes for the account.", "tags": [ "email" ] } }, "/email/mailboxes/create": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "activate_sending": { "description": "Enable outbound sending in the same call, at the cost of the activation on top of the mailbox. Default false, which creates a mailbox that can only RECEIVE.", "type": "boolean" }, "display_name": { "description": "Friendly From name shown to recipients", "type": "string" }, "domain": { "description": "A domain this account owns", "type": "string" }, "username": { "description": "Local part — the bit before the @", "type": "string" } }, "required": [ "domain", "username" ], "type": "object" } } }, "description": "Mailbox to create", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "DOMAIN_NOT_OWNED", "DOMAIN_NOT_READY", "INBOUND_MX_MISSING", "INBOUND_CHECK_FAILED", "MAILBOX_ALREADY_EXISTS", "DOMAIN_NOT_MAIL_READY", "MAIL_SERVER_UNREACHABLE", "MAILBOX_PROVISION_FAILED", "INSUFFICIENT_FUNDS", "ACTIVATION_FAILED", "SENDING_IDENTITY_NOT_COVERED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `DOMAIN_NOT_OWNED` — This account does not own that domain. Register it first, or use a domain from GET /domain/list.; `DOMAIN_NOT_READY` — The domain email setup is not complete yet. Wait a moment, then try again.; `INBOUND_MX_MISSING` — Mail to this domain has nowhere to arrive: it has no MX record and its DNS is not managed here. The refusal names the exact record to add. Nothing was created and nothing was charged.; `INBOUND_CHECK_FAILED` — The domain's inbound mail record could not be checked. Nothing was created and nothing was charged. Try again in a moment.; `MAILBOX_ALREADY_EXISTS` — A mailbox with this address already exists. Nothing was changed and nothing was charged.; `DOMAIN_NOT_MAIL_READY` — The domain is registered but the mail server does not have it yet. The mailbox was NOT created. Call POST /email/orgs/{org_id}/domains/{domain}/mail-server-resync, then try again.; `MAIL_SERVER_UNREACHABLE` — The mail server did not answer. The mailbox was NOT created and nothing was charged. Try again in a moment.; `MAILBOX_PROVISION_FAILED` — The mailbox could not be set up. It was NOT created and nothing was charged. Try again; if it persists, contact support.; `INSUFFICIENT_FUNDS` — With activate_sending, the balance must cover BOTH the mailbox and the activation. Nothing was created and nothing was charged.; `ACTIVATION_FAILED` — Returned inside the 200 body, not as the status: the mailbox WAS created and charged, and sending was not enabled. Run POST /email/sending/activate to finish.; `SENDING_IDENTITY_NOT_COVERED` — With activate_sending: the domain's verified sending identity does not cover this address, so it could never send. The refusal names the identity and the address that works. Nothing was created and nothing was charged. Without activate_sending the mailbox is still created — it can receive — and the response says it cannot send.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Provision a new mailbox on an account-owned domain. Costs 50 cents; see GET /hq/pricing. Set activate_sending to enable outbound sending in the same call — the two charges are then checked TOGETHER before either is made, so an account that can afford the mailbox but not the activation is refused outright instead of ending up with a mailbox that exists, cost money and cannot send.", "tags": [ "email" ], "x-safety": { "denylist": false, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/email/mailboxes/{address}": { "delete": { "parameters": [ { "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MAILBOX_IN_USE", "INVALID_ADDRESS", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MAILBOX_IN_USE` — The mailbox is referenced by another resource. Detach it first — see the message.; `INVALID_ADDRESS` — The address is not a valid mailbox address.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete a mailbox (idempotent: 204 whether or not it existed). Refuses with 409 MAILBOX_IN_USE when active/paused campaigns send from this address.", "tags": [ "email" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/email/mailboxes/{address}/forwarding": { "delete": { "parameters": [ { "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Stop forwarding for a mailbox. Returns 204.", "tags": [ "email" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } }, "put": { "parameters": [ { "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "forward_to": { "description": "Destination email address for forwarded mail.", "type": "string" } }, "required": [ "forward_to" ], "type": "object" } } }, "description": "Forwarding payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Forward a copy of every incoming message to an external address (server-side mail redirect). The original is kept in the mailbox.", "tags": [ "email" ], "x-safety": { "denylist": true, "disclosure": "messages_to_people", "kind": "mutate", "reverse": "DELETE /email/mailboxes/{address}/forwarding", "reversible": true, "risk": "high" } } }, "/email/mailboxes/{address}/rotate-password": { "post": { "parameters": [ { "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_ADDRESS", "MAILBOX_NOT_FOUND", "MAIL_SERVER_UNAVAILABLE", "ROTATE_HALF_APPLIED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_ADDRESS` — Send a full address like hello@example.com. Nothing was changed.; `MAILBOX_NOT_FOUND` — No mailbox with that address belongs to this account. Nothing was changed.; `MAIL_SERVER_UNAVAILABLE` — The mail server did not accept the new password. Nothing was changed.; `ROTATE_HALF_APPLIED` — The new password is live on the mail server and was not saved. Send the request again.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Give a mailbox a new password and return it once. The old password stops working immediately. The new one is not readable afterwards — rotate again if it is lost. Use this when a credential may have leaked; deleting the mailbox is not the only remedy any more.", "tags": [ "email" ], "x-safety": { "denylist": false, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/email/message/{message_id}": { "get": { "parameters": [ { "in": "path", "name": "message_id", "required": true, "schema": { "type": "string" } }, { "description": "Mailbox address that owns the message; scopes the lookup.", "in": "query", "name": "address", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MESSAGE_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MESSAGE_NOT_FOUND` — No message with that id for this account.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single message.", "tags": [ "email" ] } }, "/email/orgs/{org_id}/campaigns": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Campaigns per page (1..500, default 50).", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Opaque cursor from meta.next_cursor.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List campaigns, newest first. Pages: read meta.has_more and follow meta.next_cursor.", "tags": [ "email" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "from_address": { "description": "A mailbox on this account, from GET /email/mailboxes. Sender identity is part of the message, so one campaign sends from one address.", "type": "string" }, "name": { "description": "Identifies the campaign in listings.", "type": "string" }, "source_kind": { "description": "Where recipients come from: `crm_query` (a CRM contact filter) or `list` (explicit addresses).", "type": "string" }, "source_ref": { "additionalProperties": true, "description": "The filter for `crm_query` (stage, origin, company_id, audience_id, min/max_last_engagement_days) or {\"addresses\": [...]} for `list`.", "type": "object" }, "template_id": { "description": "A template in this org, from GET /email/orgs/{org_id}/templates.", "type": "string" } }, "required": [ "name", "template_id", "from_address", "source_kind" ], "type": "object" } } }, "description": "Campaign", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "PER_DAY_LIMIT_INVALID", "NAME_REQUIRED", "SOURCE_KIND_REQUIRED", "SOURCE_KIND_UNSUPPORTED", "SOURCE_REF_INVALID", "TEMPLATE_NOT_FOUND", "FROM_ADDRESS_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `PER_DAY_LIMIT_INVALID` — per_day_limit must be a whole number from 1 to 500.; `NAME_REQUIRED` — name identifies the campaign and cannot be empty.; `SOURCE_KIND_REQUIRED` — source_kind must be crm_query or list.; `SOURCE_KIND_UNSUPPORTED` — That source is not supported yet; use crm_query or list.; `SOURCE_REF_INVALID` — source_ref does not describe the named source.; `TEMPLATE_NOT_FOUND` — template_id must name a template in this org.; `FROM_ADDRESS_NOT_FOUND` — from_address must be a mailbox on this account.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a campaign as a draft. Nothing is resolved or sent until you call resolve.", "tags": [ "email" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /email/orgs/{org_id}/campaigns/{campaign_id}", "reversible": true, "risk": "low" } } }, "/email/orgs/{org_id}/campaigns/{campaign_id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "CAMPAIGN_NOT_FOUND", "CAMPAIGN_ACTIVE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `CAMPAIGN_NOT_FOUND` — No campaign with that id in this org.; `CAMPAIGN_ACTIVE` — The campaign is still sending. Pause or cancel it first.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete a campaign and its recipient rows. Refused while it is still sending — cancel it first, so stopping the send is a deliberate act with its own status rather than a side effect of deleting rows. Messages already sent stay in the send log, where delivery and bounce webhooks keep reconciling against them.", "tags": [ "email" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } }, "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "CAMPAIGN_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `CAMPAIGN_NOT_FOUND` — No campaign with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "One campaign, with its resolved recipient count and estimated cost when it has been resolved.", "tags": [ "email" ] }, "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "New name.", "type": "string" }, "source_kind": { "description": "crm_query or list.", "type": "string" }, "source_ref": { "additionalProperties": true, "description": "Replacement source reference.", "type": "object" } }, "type": "object" } } }, "description": "Fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "CAMPAIGN_NOT_FOUND", "CAMPAIGN_NOT_DRAFT", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `CAMPAIGN_NOT_FOUND` — No campaign with that id in this org.; `CAMPAIGN_NOT_DRAFT` — Only a draft can be edited. Create a new campaign instead of changing who a resolved one was going to reach.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Edit a DRAFT campaign. Once resolved the recipient set is frozen, so the source can no longer be changed.", "tags": [ "email" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/email/orgs/{org_id}/campaigns/{campaign_id}/cancel": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "CAMPAIGN_NOT_FOUND", "CAMPAIGN_FINISHED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `CAMPAIGN_NOT_FOUND` — No campaign with that id in this org.; `CAMPAIGN_FINISHED` — This campaign is already completed or cancelled.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "End a campaign for good. Queued recipients are dropped, so it cannot be restarted into a half-sent state.", "tags": [ "email" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/email/orgs/{org_id}/campaigns/{campaign_id}/pause": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "CAMPAIGN_NOT_FOUND", "CAMPAIGN_NOT_ACTIVE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `CAMPAIGN_NOT_FOUND` — No campaign with that id in this org.; `CAMPAIGN_NOT_ACTIVE` — Only an active campaign can be paused.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Stop sending after the message in flight. Nothing is lost or repeated: the recipient rows are the cursor.", "tags": [ "email" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/email/orgs/{org_id}/campaigns/{campaign_id}/recipients": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "string" } }, { "description": "Filter by state: queued, sent, failed or excluded.", "in": "query", "name": "state", "required": false, "schema": { "type": "string" } }, { "description": "Recipients per page (1..500, default 50).", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Opaque cursor from meta.next_cursor.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "CAMPAIGN_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `CAMPAIGN_NOT_FOUND` — No campaign with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "The resolved recipients and their state. Pages: read meta.has_more and follow meta.next_cursor.", "tags": [ "email" ] } }, "/email/orgs/{org_id}/campaigns/{campaign_id}/resolve": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "CAMPAIGN_NOT_FOUND", "CAMPAIGN_NOT_RESOLVABLE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `CAMPAIGN_NOT_FOUND` — No campaign with that id in this org.; `CAMPAIGN_NOT_RESOLVABLE` — Only a draft or ready campaign can be resolved.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Turn the source into a frozen recipient set and report who it reaches and what it would cost. Sends nothing. Suppressed, duplicate and malformed addresses are kept as excluded rows with their reason, so a count smaller than the source is explainable.", "tags": [ "email" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/email/orgs/{org_id}/campaigns/{campaign_id}/resume": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "CAMPAIGN_NOT_FOUND", "CAMPAIGN_NOT_PAUSED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `CAMPAIGN_NOT_FOUND` — No campaign with that id in this org.; `CAMPAIGN_NOT_PAUSED` — Only a paused campaign can be resumed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Resume a paused campaign, including one paused because the account could not pay. Fix the cause first — resuming does not retry the payment, the next tick does.", "tags": [ "email" ], "x-safety": { "denylist": false, "disclosure": "messages_to_people", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/email/orgs/{org_id}/campaigns/{campaign_id}/start": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "CAMPAIGN_NOT_FOUND", "CAMPAIGN_NOT_STARTABLE", "NO_RECIPIENTS", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `CAMPAIGN_NOT_FOUND` — No campaign with that id in this org.; `CAMPAIGN_NOT_STARTABLE` — Resolve the campaign first; starting commits the account to the cost.; `NO_RECIPIENTS` — The resolved set is empty, so there is nothing to send.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Begin sending a resolved campaign. It drains at the campaign's per_day_limit rather than sending at once, so it commonly stays active for days — that is the design, not a stall.", "tags": [ "email" ], "x-safety": { "denylist": true, "disclosure": "messages_to_people", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/email/orgs/{org_id}/campaigns/{campaign_id}/stats": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "CAMPAIGN_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `CAMPAIGN_NOT_FOUND` — No campaign with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Counts by recipient state, what has gone out today, and the daily limit it is pacing against.", "tags": [ "email" ] } }, "/email/orgs/{org_id}/domains/{domain}/mail-server-resync": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "domain", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Re-run mail-server provisioning for a domain. Call this when mailbox-create returns DOMAIN_NOT_MAIL_READY / MAILBOX_PROVISION_FAILED. Idempotent.", "tags": [ "email" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/email/orgs/{org_id}/gates": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Everything this org's email can be waiting on, in one place: the account pause, the org pause, each domain's sending identity (closed, pending, open, failed), and each mailbox's sending and warmup state. Each gate says what to do next. When a gate opens, the account owner is told by email once and an event is emitted (email.domain.ready, email.pause.lifted), so there is no need to poll this route.", "tags": [ "email" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/email/orgs/{org_id}/replies": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Only replies to this campaign.", "in": "query", "name": "campaign_id", "required": false, "schema": { "type": "string" } }, { "description": "true includes replies to test-mode sends.", "in": "query", "name": "test", "required": false, "schema": { "type": "boolean" } }, { "description": "Replies per page (1..200, default 50).", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Rows to skip; meta.next_cursor carries the next offset.", "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List replies people sent to this org's email, newest first. A reply is an inbound message that answers a message you sent; each one names the send, the campaign when there is one, and a sentiment (positive, neutral, negative, unsubscribe). Replies to test-mode sends are hidden unless test=true. Every reply also fires an email.replied event, so workflows, goals and watchers can act on it.", "tags": [ "email" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/email/orgs/{org_id}/template-jobs/{id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get template-generation job status", "tags": [ "email" ] } }, "/email/orgs/{org_id}/templates": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List templates for the org", "tags": [ "email" ] } }, "/email/orgs/{org_id}/templates/generate": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "Name to store the generated template under", "type": "string" }, "prompt": { "description": "What the email should say and who it is for", "type": "string" } }, "required": [ "prompt" ], "type": "object" } } }, "description": "Generation prompt", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "PROMPT_REQUIRED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `PROMPT_REQUIRED` — Send prompt in the body. No job was started.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Kick off async AI generation of an email template (returns job_id)", "tags": [ "email" ], "x-safety": { "denylist": false, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/email/orgs/{org_id}/templates/{id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete a template", "tags": [ "email" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } }, "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single template", "tags": [ "email" ] } }, "/email/orgs/{org_id}/templates/{id}/edit": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "prompt": { "description": "What to change about the current template", "type": "string" } }, "required": [ "prompt" ], "type": "object" } } }, "description": "Edit instruction", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "PROMPT_REQUIRED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `PROMPT_REQUIRED` — Send prompt in the body. The template was not changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Iterate on a template via prompt", "tags": [ "email" ], "x-safety": { "denylist": false, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/email/orgs/{org_id}/templates/{id}/send-test": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "to": { "description": "Address to send the rendered test to", "type": "string" } }, "required": [ "to" ], "type": "object" } } }, "description": "Test recipient", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "TO_REQUIRED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `TO_REQUIRED` — Send to in the body. Nothing was sent.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Send a test email rendered from the template", "tags": [ "email" ], "x-safety": { "denylist": true, "disclosure": "messages_to_people", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/email/orgs/{org_id}/verify": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "description": "Email address to verify (e.g. alice@example.com).", "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "description": "Email verify payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "EMAIL_REQUIRED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `EMAIL_REQUIRED` — Send email in the body. Nothing was checked.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Verify a single email address (sync, cheap layer only: syntax + DNS + Microsoft GetCredentialType). Returns verdict in \u003c1s for ~50% of inputs; the rest get verdict='unknown' with smtp_recommended=true.", "tags": [ "email" ], "x-safety": { "denylist": false, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/email/orgs/{org_id}/verify-bulk": { "post": { "deprecated": true, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "VERIFY_BULK_RETIRED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `VERIFY_BULK_RETIRED` — Bulk verification is gone. No job was created. Use POST /email/orgs/{org_id}/verify per address.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "RETIRED. Answers 410 and creates nothing. Verify one address at a time with POST /email/orgs/{org_id}/verify, which answers immediately.", "tags": [ "email" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/email/orgs/{org_id}/verify-jobs/{id}": { "get": { "deprecated": true, "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "JOB_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `JOB_NOT_FOUND` — No job with that id belongs to this account.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Read a bulk email-verification job created before the bulk path was retired. No new jobs can be created.", "tags": [ "email" ] } }, "/email/outbox/{address}": { "get": { "parameters": [ { "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List outbox for a specific mailbox", "tags": [ "email" ] } }, "/email/send": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "attachments": { "description": "Files to attach. Each entry is {upload_id, filename}: stage the bytes with POST /storage/orgs/{org_id}/uploads/begin, PUT them, commit, then send the upload_id here. The file is attached to the message itself — it does not become a public URL. 10MB each.", "items": { "additionalProperties": true, "description": "An attachment", "type": "object" }, "type": "array" }, "from": { "description": "Sending mailbox address. Must be a mailbox on a domain you own, with sending activated.", "type": "string" }, "html": { "description": "HTML body", "type": "string" }, "subject": { "description": "Subject line. Taken from the template when template_id is used.", "type": "string" }, "template_id": { "description": "Render from a stored template instead of supplying html/text", "type": "string" }, "template_vars": { "additionalProperties": true, "description": "Values substituted into the template placeholders", "type": "object" }, "test": { "description": "Test mode: deliver to the ACCOUNT OWNER instead of the listed recipients, subject marked [TEST]. The whole pipeline runs for real; only the destination changes. Default false.", "type": "boolean" }, "text": { "description": "Plain-text body — the fallback part for clients that will not render HTML", "type": "string" }, "to": { "description": "Recipient address(es). A bare string is accepted for a single recipient.", "items": { "description": "Recipient email address", "type": "string" }, "type": "array" } }, "required": [ "from", "to" ], "type": "object" } } }, "description": "Message. Supply html and/or text, or a template_id.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NO_OWNER_EMAIL", "ATTACHMENT_UPLOAD_REQUIRED", "ATTACHMENT_NOT_FOUND", "ATTACHMENT_TOO_LARGE", "UNSUPPORTED_FIELD", "ORG_PAUSED", "ACCOUNT_PAUSED", "SENDING_NOT_PROVISIONED", "SEND_FAILED", "SENDING_IDENTITY_NOT_COVERED", "SENDING_IDENTITY_NOT_VERIFIED", "TOO_MANY_RECIPIENTS", "INVALID_RECIPIENT", "ADDRESS_SUPPRESSED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NO_OWNER_EMAIL` — Test mode needs an account owner email to deliver to. Nothing was sent.; `ATTACHMENT_UPLOAD_REQUIRED` — Each attachment needs an upload_id. Nothing was sent.; `ATTACHMENT_NOT_FOUND` — An attachment upload_id names no staged upload in an org this account owns. Nothing was sent.; `ATTACHMENT_TOO_LARGE` — An attachment is over 10MB. Nothing was sent.; `UNSUPPORTED_FIELD` — cc or bcc was sent. They are not supported and NOTHING was sent — this endpoint delivers one message PER recipient, so a copied recipient would not share the message's headers. Put every recipient in `to`.; `ORG_PAUSED` — Sending is paused for this org: too much of its recent mail bounced or was marked as spam. This is scoped to the org that sent it, so other orgs on the account are unaffected. Remove the addresses that bounce, then POST /hq/account/resume-sending.; `ACCOUNT_PAUSED` — Sending is paused for the whole account, which happens when the bounce or complaint rate is bad across every org rather than in one. Same remedy: fix the addresses, then POST /hq/account/resume-sending.; `SENDING_NOT_PROVISIONED` — This account has no outbound-email credential yet. The mailbox and domain are fine — the account itself is not set up. Call POST /email/sending/activate on the mailbox to set it up. Nothing was charged and no message was sent.; `SEND_FAILED` — The message could not be relayed. Nothing was charged and no message was sent. Retry; if it persists the relay is degraded.; `SENDING_IDENTITY_NOT_COVERED` — The From address is not covered by the domain's verified sending identity, so retrying cannot help. The refusal names the identity and the address that works. Nothing was charged and no message was sent.; `SENDING_IDENTITY_NOT_VERIFIED` — The sending identity for this From address is not verified yet. The message names each identity and its state: still being verified means wait for the email that says it is ready; failed means re-run the email setup for the domain; no sending identity means set one up with POST /domain/orgs/{org_id}/{domain}/email-infra. This is a configuration fault, so retrying does not help. Nothing was charged and no message was sent. See GET /domain/orgs/{org_id}/{domain}/status for the current state of each identity.; `TOO_MANY_RECIPIENTS` — The recipient list is over the per-send cap. Split the send.; `INVALID_RECIPIENT` — A `to` address is not a valid email address. Nothing was sent or charged. This is permanent — fix the address rather than retrying it.; `ADDRESS_SUPPRESSED` — This address bounced or complained before, so the send was REFUSED.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Send an email. Supports Idempotency-Key header for retry safety (24h TTL).", "tags": [ "email" ], "x-safety": { "denylist": true, "disclosure": "messages_to_people", "kind": "mutate", "reversible": false, "risk": "high", "test_mode": true } } }, "/email/sending/activate": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "address": { "description": "Full mailbox address", "type": "string" } }, "required": [ "address" ], "type": "object" } } }, "description": "Mailbox", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "ALREADY_ACTIVATED", "MAILBOX_NOT_OWNED", "SENDING_NOT_PROVISIONED", "SENDING_IDENTITY_NOT_COVERED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `ALREADY_ACTIVATED` — Sending is already enabled on this mailbox. Nothing was changed and nothing was charged.; `MAILBOX_NOT_OWNED` — This mailbox does not belong to the calling account.; `SENDING_NOT_PROVISIONED` — The account could not be set up for outbound email. Nothing was charged and sending is NOT enabled. Retry; if it persists, contact support.; `SENDING_IDENTITY_NOT_COVERED` — The domain's verified sending identity does not cover this address, so every send from it would be refused. The refusal names the identity and the address that works. Sending is NOT enabled and nothing was charged.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Enable outbound sending for a mailbox. Costs $2.50, on top of the 50 cents the mailbox cost; see GET /hq/pricing. Sets up the account's sending credential if it does not have one yet, then enables the mailbox and grants its initial quota. To create and activate in one call, use activate_sending on POST /email/mailboxes/create.", "tags": [ "email" ], "x-safety": { "denylist": false, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/email/sent": { "get": { "parameters": [ { "description": "Messages per page (1..200, default 50). Out-of-range values fall back to 50.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Messages to skip (default 0).", "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List sent messages for the account, newest first.", "tags": [ "email" ] } }, "/email/status/{message_id}": { "get": { "parameters": [ { "in": "path", "name": "message_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MESSAGE_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MESSAGE_NOT_FOUND` — No message with that id for this account.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get delivery status for a sent message", "tags": [ "email" ] } }, "/email/templates/{id}/preview": { "get": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Public preview of a template (browser-friendly)", "tags": [ "email" ] } }, "/email/unsubscribe/{tok}": { "get": { "parameters": [ { "in": "path", "name": "tok", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Direct-link unsubscribe — same effect as POST; for older clients.", "tags": [ "email" ] }, "post": { "parameters": [ { "in": "path", "name": "tok", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "RFC 8058 one-click unsubscribe. Adds the recipient to suppressed_addresses with reason='unsubscribe'.", "tags": [ "email" ] } }, "/email/warmup/pause": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "address": { "description": "Full mailbox address", "type": "string" } }, "required": [ "address" ], "type": "object" } } }, "description": "Mailbox", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Pause warmup for a mailbox", "tags": [ "email" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/email/warmup/resume": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "address": { "description": "Full mailbox address", "type": "string" } }, "required": [ "address" ], "type": "object" } } }, "description": "Mailbox", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Resume warmup for a mailbox", "tags": [ "email" ], "x-safety": { "denylist": false, "disclosure": "messages_to_people", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/email/warmup/start": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "address": { "description": "Full mailbox address to warm up", "type": "string" } }, "required": [ "address" ], "type": "object" } } }, "description": "Mailbox", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MAILBOX_NOT_OWNED", "SENDING_NOT_ACTIVATED", "WARMUP_ALREADY_ACTIVE", "SENDING_NOT_PROVISIONED", "MAILBOX_NOT_PROVISIONED", "SENDING_IDENTITY_MISSING", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MAILBOX_NOT_OWNED` — This mailbox does not belong to the calling account.; `SENDING_NOT_ACTIVATED` — Sending is not enabled on this mailbox. Warmup was NOT started. Call POST /email/sending/activate on the address first.; `WARMUP_ALREADY_ACTIVE` — Warmup is already running on this mailbox. Nothing was changed.; `SENDING_NOT_PROVISIONED` — The account has no sending credential, so warmup was NOT started. Call POST /email/sending/activate on the address to set one up.; `MAILBOX_NOT_PROVISIONED` — This mailbox has no stored password, so warmup was NOT started. Call POST /email/orgs/{org_id}/domains/{domain}/mail-server-resync to give it one.; `SENDING_IDENTITY_MISSING` — The verified identity does not cover this address, so it cannot be the From of a message. Warmup was NOT started and NOTHING was charged — warmup only sends from this address, so it cannot do anything until the address's own domain is verified.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Start warmup for a mailbox: a slow ramp of real exchanges that builds the address's sending reputation before it carries your mail. Refused, free of charge, when the account's verified identity does not cover the address — warmup does nothing but send from it, so it cannot work until that is fixed.", "tags": [ "email" ], "x-safety": { "denylist": true, "disclosure": "messages_to_people", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/email/warmup/stats/{address}": { "get": { "parameters": [ { "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MAILBOX_NOT_OWNED", "WARMUP_NOT_ACTIVE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MAILBOX_NOT_OWNED` — This mailbox does not belong to the calling account.; `WARMUP_NOT_ACTIVE` — Warmup is not active on this mailbox, so there are no stats. Start it with POST /email/warmup/start.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get warmup throughput / inbox-placement stats. Requires warmup to be active on the mailbox — a mailbox that never started warmup has no stats.", "tags": [ "email" ] } }, "/email/warmup/stop": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "address": { "description": "Full mailbox address", "type": "string" } }, "required": [ "address" ], "type": "object" } } }, "description": "Mailbox", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Stop warmup for a mailbox and remove it from the warmup pool", "tags": [ "email" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/email/webhook/ses": { "post": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delivery provider webhook for deliveries, bounces and complaints (public; every notification is signature-verified before it is trusted)", "tags": [ "email" ] } }, "/events/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of events: method, path, auth, params, error codes — public, no auth", "tags": [ "events" ] } }, "/events/orgs/{org_id}/subscriptions": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List this org's event subscriptions. Secrets are never returned.", "tags": [ "events" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "kinds": { "description": "Event kinds to receive, for example [\"comment.submitted\"] or [\"comment.*\"]. A trailing * matches a namespace. There is deliberately no way to subscribe to everything.", "items": { "description": "An event kind or namespace glob", "type": "string" }, "type": "array" }, "url": { "description": "https destination. Checked at create AND on every delivery, so a name repointed at a private address later is refused then too.", "type": "string" } }, "required": [ "url", "kinds" ], "type": "object" } } }, "description": "The subscription", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "URL_REQUIRED", "URL_NOT_HTTPS", "URL_NOT_REACHABLE", "KINDS_REQUIRED", "KIND_INVALID", "SUBSCRIPTION_LIMIT", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `URL_REQUIRED` — Send url: where deliveries should be POSTed. Nothing was created.; `URL_NOT_HTTPS` — The destination must be https. Nothing was created.; `URL_NOT_REACHABLE` — The destination resolves to a private or loopback address. Nothing was created.; `KINDS_REQUIRED` — Send kinds: the event kinds you want. Nothing was created.; `KIND_INVALID` — An entry in kinds is empty or contains a comma or quote. Nothing was created.; `SUBSCRIPTION_LIMIT` — This org is at the limit of 10 event subscriptions. Delete one, or widen an existing subscription's kinds. Nothing was created.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Subscribe a destination to this org's events. The signing secret is returned ONCE and is never readable afterwards — rotate it if you lose it. Deliveries are POSTed as JSON with X-MyAPI-Event-Id (stable across retries, key your idempotency on it), X-MyAPI-Timestamp and X-MyAPI-Signature: sha256=HMAC-SHA256(secret, timestamp + \".\" + body). Retries run at 1m, 5m, 30m, 2h and 6h, then stop, and any past delivery can be sent again with .../deliveries/{delivery_id}/replay. Ordering is NOT guaranteed — order by occurred_at in the payload. Events from test-mode actions ARE delivered, carrying \"test\": true in the payload: integration testing is exactly when you want the doorbell, so your receiver should branch on that flag rather than expect silence. Ten subscriptions per org.", "tags": [ "events" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /events/orgs/{org_id}/subscriptions/{id}", "reversible": true, "risk": "low" } } }, "/events/orgs/{org_id}/subscriptions/{id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SUBSCRIPTION_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SUBSCRIPTION_NOT_FOUND` — No subscription with that id in this org. Nothing was deleted.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete a subscription and its delivery history.", "tags": [ "events" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } }, "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "active": { "description": "false pauses delivery; true resumes it and clears the failure count.", "type": "boolean" }, "kinds": { "description": "Replaces the current list.", "items": { "description": "An event kind or namespace glob", "type": "string" }, "type": "array" }, "url": { "description": "New https destination.", "type": "string" } }, "type": "object" } } }, "description": "Fields to change — omitted fields are left alone", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SUBSCRIPTION_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SUBSCRIPTION_NOT_FOUND` — No subscription with that id in this org. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Change a subscription's url or kinds, or set active to resume one that was paused after repeated failures. Resuming clears the failure count.", "tags": [ "events" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/events/orgs/{org_id}/subscriptions/{id}/deliveries": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "What was attempted for this subscription, newest first: one row per ATTEMPT with the status, the response code and the error. A give-up is kept as status=dead rather than disappearing.", "tags": [ "events" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/events/orgs/{org_id}/subscriptions/{id}/deliveries/{delivery_id}/replay": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "delivery_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "DELIVERY_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `DELIVERY_NOT_FOUND` — No delivery with that id in this org, or the event behind it is no longer stored. Nothing was sent.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Send one past delivery again, now. The event id is preserved, so a receiver keying idempotency on X-MyAPI-Event-Id sees a repeat rather than a new fact. The replay is recorded as its own attempt in the delivery log — it does not rewrite the original.", "tags": [ "events" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/events/orgs/{org_id}/subscriptions/{id}/rotate": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SUBSCRIPTION_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SUBSCRIPTION_NOT_FOUND` — No subscription with that id in this org. The secret was NOT rotated.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Issue a new signing secret. The old one stops verifying immediately, so deploy the new secret before rotating or you will reject your own deliveries. Returned ONCE.", "tags": [ "events" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/events/orgs/{org_id}/subscriptions/{id}/test": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SUBSCRIPTION_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SUBSCRIPTION_NOT_FOUND` — No subscription with that id in this org. Nothing was sent.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Send a synthetic event.test to this subscription now and report what the destination answered. Use it to check your endpoint and signature verification without waiting for something real to happen.", "tags": [ "events" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/feedback/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of feedback: method, path, auth, params, error codes — public, no auth", "tags": [ "feedback" ] } }, "/feedback/in/shot.js": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Serve the screenshot renderer the widget loads on demand. Returns JavaScript. You do not embed this — widget.js fetches it when a person opens the feedback sheet, which is why it is not part of the widget script itself.", "tags": [ "feedback" ] } }, "/feedback/in/{key}": { "post": { "parameters": [ { "in": "path", "name": "key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "body": { "description": "What they wrote. Up to 8000 characters; longer is refused rather than truncated.", "type": "string" }, "end_user_ref": { "description": "Who is reporting, as your own identifier for them — set by calling identify() on the widget, not by hand. Opaque to us: it is stored, returned when you read the feedback, and never resolved against anything. Up to 200 characters; longer is cut rather than refused, because a label must not be able to lose a bug report.", "type": "string" }, "kind": { "description": "What the person says this is", "enum": [ "bug", "issue", "suggestion" ], "type": "string" }, "page_url": { "description": "Where they were.", "type": "string" }, "reporter_token": { "description": "The browser-scoped token that makes this report the filer's own, so they can see and confirm it later. Normally sent in the X-Feedback-Reporter header; accepted here for the no-header path. Opaque and high-entropy — minted and held by the widget, never issued by us, and naming no org.", "type": "string" }, "route": { "description": "Application route, if the app knows it.", "type": "string" }, "target_context": { "additionalProperties": true, "description": "What the target WAS, not where it sits: its text, tag, role, aria-label, the heading it is under. A selector tells a reader nothing about whether the button said \"Save\" or \"Delete account\". Never include what someone typed into a field.", "type": "object" }, "target_label": { "description": "Accessible name or trimmed text of the pointed element — what it WAS, not where it sits. The widget re-anchors a pin label -\u003e selector -\u003e region on a later visit, so the label outlives the refactor that moves the selector.", "type": "string" }, "target_region": { "additionalProperties": true, "description": "Region they dragged, as {x,y,w,h} in viewport pixels.", "type": "object" }, "target_selector": { "description": "CSS selector of the element they clicked.", "type": "string" }, "trace": { "description": "The steps before the report — clicks, route changes, console errors, failed requests — as {t,kind,detail}. This is the reproduction, which is the part people leave out of bug reports. Up to 16 KB; a larger one is dropped and the feedback is still kept.", "items": { "additionalProperties": true, "description": "event", "type": "object" }, "type": "array" }, "viewport": { "additionalProperties": true, "description": "Viewport size as {w,h}.", "type": "object" } }, "required": [ "kind", "body" ], "type": "object" } } }, "description": "Feedback from a visitor", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "WIDGET_NOT_FOUND", "ORIGIN_NOT_ALLOWED", "RATE_LIMITED", "INVALID_KIND", "BODY_REQUIRED", "BODY_TOO_LONG", "BODY_TOO_LARGE" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `WIDGET_NOT_FOUND` — No active widget with that key. A revoked key reads the same as an invented one.; `ORIGIN_NOT_ALLOWED` — This widget does not accept submissions from that origin.; `RATE_LIMITED` — Too much feedback from one place too quickly.; `INVALID_KIND` — kind must be bug, issue or suggestion.; `BODY_REQUIRED` — Feedback needs something written in it.; `BODY_TOO_LONG` — Over 8000 characters. Nothing was saved.; `BODY_TOO_LARGE` — The whole request is over 64 KB, usually an oversized trace. Nothing was saved." } }, "summary": "Submit feedback from an end-user, without authentication. The key names a widget and therefore an org; it is PUBLIC — it ships in your page source and is not a secret. It cannot be used to read anything. Set allowed_origins on the widget to stop other sites posting with a key they found.", "tags": [ "feedback" ] } }, "/feedback/in/{key}/edit": { "post": { "parameters": [ { "in": "path", "name": "key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "funnel_id": { "description": "The funnel whose page is being edited.", "type": "string" }, "identity_token": { "description": "A verified id_token from your auth tenant for the signed-in end-user. Its tenant must be this widget's org and it must carry edit_content in myapi_capabilities.", "type": "string" }, "new_text": { "description": "What to put in its place. Empty deletes the text. Stored as text, never markup.", "type": "string" }, "old_text": { "description": "The exact text to replace. It must occur once on the page; zero or many matches are refused.", "type": "string" }, "slug": { "description": "The page within the funnel, e.g. index.html.", "type": "string" }, "target_selector": { "description": "The element the editor pointed at, recorded for audit.", "type": "string" } }, "required": [ "identity_token", "funnel_id", "slug", "old_text" ], "type": "object" } } }, "description": "The content edit", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "IDENTITY_REQUIRED", "IDENTITY_INVALID", "EDIT_NOT_ALLOWED", "TARGET_REQUIRED", "OLD_TEXT_REQUIRED", "FUNNEL_NOT_FOUND", "PAGE_NOT_FOUND", "OLD_TEXT_NOT_FOUND", "OLD_TEXT_AMBIGUOUS", "EDIT_UNAVAILABLE" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `IDENTITY_REQUIRED` — No identity token. Sign in and send a verified identity_token.; `IDENTITY_INVALID` — The identity token is not valid for this widget's org.; `EDIT_NOT_ALLOWED` — This user does not hold the edit_content capability.; `TARGET_REQUIRED` — funnel_id and slug are required.; `OLD_TEXT_REQUIRED` — old_text is required.; `FUNNEL_NOT_FOUND` — No funnel with that id for this org.; `PAGE_NOT_FOUND` — No live page at that slug.; `OLD_TEXT_NOT_FOUND` — old_text is not on the page. Nothing was changed.; `OLD_TEXT_AMBIGUOUS` — old_text appears more than once. Nothing was changed.; `EDIT_UNAVAILABLE` — Content edit is not available on this deployment." } }, "summary": "Apply an in-place content edit to a funnel page, as a signed-in end-user who holds the edit_content capability. This is not the public report path: it needs a VERIFIED identity_token from your auth tenant (its tenant must be this widget's org) that carries edit_content in myapi_capabilities — an anonymous or under-capable caller is refused. The edit is content-only: it replaces old_text with new_text inside a single text node, never markup, attributes or script. old_text must be unique on the page; zero or many matches are refused and nothing changes. The change publishes through funnel version history, so it is undoable.", "tags": [ "feedback" ] } }, "/feedback/in/{key}/items/{id}/confirm": { "post": { "parameters": [ { "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_FOUND" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_FOUND` — No feedback with that id for this widget in a state you can confirm." } }, "summary": "Confirm that a claimed fix works, closing the report. Send the browser's token in X-Feedback-Reporter. Succeeds only when the token filed the item AND the item is resolved_claimed — the team has said it is fixed and is waiting for you. A token that did not file it, an id from another site, or an item not waiting for confirmation all answer the same not-found, so the endpoint cannot be used to probe which reports exist.", "tags": [ "feedback" ] } }, "/feedback/in/{key}/items/{id}/reopen": { "post": { "parameters": [ { "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "message": { "description": "What is still wrong. Optional; added to the thread for the team.", "type": "string" } }, "type": "object" } } }, "description": "Why it is still broken", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_FOUND" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_FOUND` — No feedback with that id for this widget in a state you can reopen." } }, "summary": "Reopen a report the team claimed to have fixed, because it is still broken. Send the browser's token in X-Feedback-Reporter and an optional note. The item goes back to open for the team and your note is added to the thread. Same not-found rule as confirm: only the token that filed a resolved_claimed item can reopen it.", "tags": [ "feedback" ] } }, "/feedback/in/{key}/items/{id}/screenshot": { "post": { "parameters": [ { "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "WIDGET_NOT_FOUND", "NOT_FOUND", "EMPTY_UPLOAD", "SCREENSHOT_TOO_LARGE", "NOT_AN_IMAGE", "SCREENSHOT_NOT_STORED", "RATE_LIMITED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `WIDGET_NOT_FOUND` — No active widget with that key.; `NOT_FOUND` — No feedback with that id for this widget.; `EMPTY_UPLOAD` — The request had no image in it.; `SCREENSHOT_TOO_LARGE` — Over 3 MB. The feedback was kept without it.; `NOT_AN_IMAGE` — The bytes are not a PNG, JPEG or WebP.; `SCREENSHOT_NOT_STORED` — The image could not be stored. The feedback was kept without it.; `RATE_LIMITED` — Too many uploads from one place too quickly." } }, "summary": "Attach a screenshot to feedback already submitted with this widget key. Send the raw image bytes (PNG, JPEG or WebP), up to 3 MB. Separate from the submission on purpose: the feedback is saved first, so a picture that fails to render or upload never costs the report. The image is stored private in your org's assets; listing feedback returns a signed link to it that is good for an hour. If the capture FAILED, post `{\"error\":\"…\"}` as application/json instead of bytes — the item then carries screenshot_status=failed and that message, so a page the renderer cannot handle is a fact you can read rather than a missing picture you have to guess about.", "tags": [ "feedback" ] } }, "/feedback/in/{key}/mine": { "get": { "parameters": [ { "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "description": "Show only reports filed on this application route.", "in": "query", "name": "route", "required": false, "schema": { "type": "string" } }, { "description": "The page-asserted end-user id (the value passed to the widget's identify()). Also returns reports this user filed while identified — from any browser or device, and from before this browser had a token. Unverified and spoofable: it exposes only the feedback of the user the page claims to be.", "in": "query", "name": "user", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "List the feedback the caller filed with this widget. The caller is named two ways and an item is theirs if either matches: the browser's token in the X-Feedback-Reporter header (the widget mints and stores it, and it makes a report \"this browser's\"), and the user query parameter — the id the host app passed to identify() — which links the reports this user filed while identified, across their browsers and devices, including notes filed before this browser had a token. The two are OR-ed and de-duped, so an item that matches both appears once. Returns only the states you still care about (open, resolved_claimed, reopened); confirmed and deleted are left out. Each item carries its anchor (target_label, target_selector, target_region) so the widget can re-pin it, plus the thread, where the team's reply appears. No org data and no other caller's items are ever returned; when neither token nor user is given, the list is empty, not an error. SECURITY: user is a page-asserted, unverified identifier, so this read shows only the feedback of the user the page claims to be, to that page; signed identity is the planned hardening. The confirm and reopen actions do NOT accept user and stay token-only.", "tags": [ "feedback" ] } }, "/feedback/in/{key}/widget.js": { "get": { "parameters": [ { "in": "path", "name": "key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Serve the embeddable feedback widget for a key, with that widget's routes and theme compiled in. Returns JavaScript, not JSON. Paste `\u003cscript src=\"…/feedback/in/{key}/widget.js\" async\u003e\u003c/script\u003e` into your pages and end-users get a button that points at an element and files feedback. Cached for 5 minutes, so a change to routes or theme reaches a browser within that; revoking a key stops submissions at once. If your site sets a Content-Security-Policy, add this host to script-src — the widget adds no inline script and calls nothing else. Call `window.__myapiFeedback.identify(\"your-user-id\")` once you know who is using the app and every report carries it back to you; call it with nothing on sign-out. To keep part of a page out of reports entirely, mark it `data-feedback-ignore` — it is skipped in the element context AND blacked out in the screenshot.", "tags": [ "feedback" ] } }, "/feedback/orgs/{org_id}/items": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Filter to bug, issue or suggestion.", "in": "query", "name": "kind", "required": false, "schema": { "type": "string" } }, { "description": "Filter by status, e.g. open or resolved.", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "description": "Filter by whether the picture made it: pending, ok, failed, or none (no capture was ever attempted). A run of failed items usually shares one cause on the reporting page — this is how you see the run in one query instead of re-reading reports one by one.", "in": "query", "name": "screenshot_status", "required": false, "schema": { "type": "string" } }, { "description": "Items per page (1..200, default 50).", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Items to skip.", "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_SCREENSHOT_STATUS", "INVALID_KIND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_SCREENSHOT_STATUS` — screenshot_status must be pending, ok, failed or none.; `INVALID_KIND` — kind must be bug, issue or suggestion. Each item carries `testable`: true when its trace holds a console error or a failed request, which is what GET .../items/{id}/test needs to write assertions. A report without one still renders, but the file says so and fails loudly instead of asserting nothing — so `testable` is how you find the reports that can become a failing test right now.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List feedback for the org, newest first. `total` is the number of MATCHES and `has_more` flags a truncated page — both describe the whole match set, not the page.", "tags": [ "feedback" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "body": { "description": "What they wrote. Up to 8000 characters; a longer body is refused rather than truncated, so nothing is silently lost.", "type": "string" }, "kind": { "description": "What the person says this is", "enum": [ "bug", "issue", "suggestion" ], "type": "string" }, "page_url": { "description": "Where they were.", "type": "string" }, "route": { "description": "Application route, if the app knows it — more stable than a URL for grouping.", "type": "string" }, "target_context": { "additionalProperties": true, "description": "What the target WAS, not where it sits: its text, tag, role, aria-label, the heading it is under.", "type": "object" }, "target_label": { "description": "Accessible name or trimmed text of the pointed element — what it WAS, so a pin survives a refactor that moves the selector.", "type": "string" }, "target_region": { "additionalProperties": true, "description": "Region they dragged, as {x,y,w,h} in viewport pixels.", "type": "object" }, "target_selector": { "description": "CSS selector of the element they clicked.", "type": "string" }, "trace": { "description": "The steps before the report — clicks, route changes, console errors, failed requests — as {t,kind,detail}.", "items": { "additionalProperties": true, "description": "event", "type": "object" }, "type": "array" }, "viewport": { "additionalProperties": true, "description": "Viewport size as {w,h}, so a region can be interpreted later.", "type": "object" } }, "required": [ "kind", "body" ], "type": "object" } } }, "description": "Feedback", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Recorded feedback", "properties": { "id": { "description": "Feedback id.", "type": "string" }, "kind": { "description": "As submitted.", "type": "string" }, "status": { "description": "open.", "type": "string" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_KIND", "BODY_REQUIRED", "BODY_TOO_LONG", "BODY_TOO_LARGE", "INVALID_JSON", "RATE_LIMITED", "INVALID_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_KIND` — kind must be bug, issue or suggestion.; `BODY_REQUIRED` — Feedback needs something written in it.; `BODY_TOO_LONG` — Over 8000 characters. Nothing was saved — resend a shorter body.; `BODY_TOO_LARGE` — The whole request is over 64 KB, usually an oversized trace. Nothing was saved.; `INVALID_JSON` — The request body is not valid JSON.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Record one piece of feedback from an end-user. `kind` is chosen by the person, not inferred: someone reporting a bug is telling you they believe the product is broken, which classification cannot recover. Include target_selector or target_region to record WHERE they were pointing — that is the difference between \"the button is broken\" and a report that can be acted on without a reproduction call.", "tags": [ "feedback" ] } }, "/feedback/orgs/{org_id}/items/{id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete a piece of feedback for good. Resolve closes an item and keeps it; this erases it. Submissions arrive through a public endpoint, so an inbox collects spam and the occasional message where somebody typed personal details into a bug report — this is how you remove those. Idempotent: 204 whether or not the item existed.", "tags": [ "feedback" ] } }, "/feedback/orgs/{org_id}/items/{id}/close": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_FOUND` — No open feedback with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Force-close a piece of feedback without waiting for the filer. The filer's confirmation is the normal close; this is the escape hatch for when the reporter is gone. It moves any non-confirmed item straight to confirmed. Already-confirmed and not-found answer the same way, so an id cannot be probed across orgs.", "tags": [ "feedback" ] } }, "/feedback/orgs/{org_id}/items/{id}/comment": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "message": { "description": "The message to post to the thread, shown to the reporter.", "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "description": "The comment", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MESSAGE_REQUIRED", "NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MESSAGE_REQUIRED` — message is required and cannot be empty. Nothing was posted.; `NOT_FOUND` — No feedback with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Post a message to a feedback item's thread WITHOUT changing its state. The thread records who said what and when, and the reporter sees it — use this to post progress (\"working on this\") between the report and the fix. For a note that accompanies a fix, pass `reply` to resolve instead.", "tags": [ "feedback" ] } }, "/feedback/orgs/{org_id}/items/{id}/resolve": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "change_ref": { "description": "The change that fixed it — a commit, a pull request, a deploy id. Shown to the filer as provenance. Optional.", "type": "string" }, "reply": { "description": "What you changed, shown to the filer on the thread. Optional.", "type": "string" }, "resolved_version": { "description": "The build that carries the fix — a hash, a tag, a date, whatever your app declares as its version. Never parsed. Combined with the page the report was filed on, it gives the filer a link straight to the fixed screen. Optional.", "type": "string" } }, "type": "object" } } }, "description": "Optional note to the filer", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_FOUND` — No open feedback with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Claim a piece of feedback as fixed and wait for the filer to confirm. This is a CLAIM, not a close: the item moves to resolved_claimed and the person who filed it confirms the fix or reopens it. Their confirmation is the real close. Pass an optional {reply} and it is recorded on the thread for the filer to read. Claimable only from open, in_progress or reopened; any other state, another org's id, and a missing id all answer the same not-found, so an id cannot be probed across orgs. Use POST .../close to force-close when the reporter never returns. Pass resolved_version and the filer's list carries a review_url — the screen they reported, on the build that fixes it — so confirming is a click rather than a hunt through a changelog.", "tags": [ "feedback" ] } }, "/feedback/orgs/{org_id}/items/{id}/start": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "message": { "description": "What is happening, shown to the filer on the thread. Optional.", "type": "string" } }, "type": "object" } } }, "description": "Optional note to the filer", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_FOUND` — No open feedback with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Mark a piece of feedback as being worked on: open or reopened moves to in_progress. This is for the FILER's benefit — the widget shows the item's status in place, and without this call the gap between \"received\" and \"marked fixed\" is silence. Pass an optional {message} and the filer reads it on the thread. resolve accepts in_progress, so start then resolve is the normal path for an agent processing a report.", "tags": [ "feedback" ] } }, "/feedback/orgs/{org_id}/items/{id}/test": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Base URL the test should drive, e.g. https://staging.example.com. Defaults to the origin of the reported page_url.", "in": "query", "name": "base", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_FOUND", "BASE_URL_REQUIRED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_FOUND` — No feedback with that id in this org.; `BASE_URL_REQUIRED` — The report has no page_url to take a base URL from — pass ?base=.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Render this feedback item as a Playwright regression test. Returns JavaScript, not JSON — redirect it into a spec file, or hand it to the agent fixing the bug. A report that carries a route, an element and a trace of clicks, console errors and failed requests already IS a test: the errors ARE the failure, so the generated assertions are that they no longer happen. It fails on the reported state and passes once the bug is fixed. If the trace holds nothing a machine can call broken — the page said the wrong thing rather than throwing — the file says so and fails loudly instead of asserting nothing. Clicks locate by accessible name, not by the recorded CSS path, because the path dies at the next refactor. Pass ?base= to run it somewhere other than the origin the report came from. A report is testable when its trace carries a console error, a script error or a failed request: the accepted event kinds are console, error and request, and their dotted forms (console.error, request.failed) count too. Anything else — clicks, route changes — has nothing a machine can call broken, and the generated file says so and fails loudly rather than asserting nothing.", "tags": [ "feedback" ] } }, "/feedback/orgs/{org_id}/widgets": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Rows per page (1..500, default 50). Out-of-range values are rejected with 400 rather than clamped — a caller who asks for 5000 and silently gets 500 believes they have the whole list.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Keyset cursor — pass the previous page's meta.next_cursor. Absent on the last page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List active widgets for the org, newest first, each with the script tag to paste. Keys are shown in full — a widget key is public by construction and ships in your page source.", "tags": [ "feedback" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "allowed_origins": { "description": "Origins that may post, e.g. https://app.example.com. Empty means any origin.", "items": { "description": "origin", "type": "string" }, "type": "array" }, "capture": { "additionalProperties": true, "description": "What the widget may collect: screenshot and text, each true or false, both true unless you say otherwise. Same shape as PATCH, so a widget can be created with capture already off for a site that shows customer records.", "type": "object" }, "name": { "description": "Label for your own reference.", "type": "string" }, "notify_url": { "description": "Absolute http(s) URL that receives a POST for every item lifecycle change (feedback.item.created, .reopened, .confirmed). Same field as PATCH; empty means no push.", "type": "string" }, "routes": { "description": "Where the widget appears, matched against the page path in the browser. Same syntax as PATCH: `*` inside a segment, `**` across them, a leading ! to hide. Empty shows it everywhere you paste the script.", "items": { "description": "pattern", "type": "string" }, "type": "array" }, "theme": { "additionalProperties": true, "description": "accent (a colour like #2563eb), position (a corner) and label (the button text).", "type": "object" } }, "type": "object" } } }, "description": "Widget", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_CAPTURE", "INVALID_ROUTE", "INVALID_THEME", "INVALID_NOTIFY_URL", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_CAPTURE` — capture takes screenshot and text, each true or false.; `INVALID_ROUTE` — A route pattern does not start with / or is too long.; `INVALID_THEME` — theme takes accent, position and label, and each has a fixed shape.; `INVALID_NOTIFY_URL` — notify_url must be an absolute http or https URL, up to 2048 characters.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Mint a public widget key for a site. The key is NOT a secret — it ships in page source. It names your org and can be revoked; it authenticates nobody. Set allowed_origins so another site cannot post with a key it found, bearing in mind an Origin header stops a browser, not a script.", "tags": [ "feedback" ] } }, "/feedback/orgs/{org_id}/widgets/{id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_FOUND` — No active widget with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Revoke a widget key. Submissions with it stop immediately; feedback already collected is kept.", "tags": [ "feedback" ] }, "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "allowed_origins": { "description": "Origins that may post. Empty means any origin.", "items": { "description": "origin", "type": "string" }, "type": "array" }, "capture": { "additionalProperties": true, "description": "What the widget is allowed to collect: screenshot (true or false) and text (true or false). Both are true unless you say otherwise. Merged key by key, so `{\"text\": false}` leaves your screenshot setting alone; send null for a key to restore its default. Set screenshot to false and no picture is taken at all — a screenshot of a working page is a picture of whatever that page holds, and on a screen showing customer records that is their data, not yours to send. Set text to false and the report carries the shape of the element you pointed at — its tag, role and id — without the words in it. Mark any element `data-feedback-ignore` to keep it out of both: it is skipped in the report and blacked out in the picture. Takes effect in browsers within 5 minutes; you do not redeploy your site.", "type": "object" }, "name": { "description": "Label for your own reference.", "type": "string" }, "notify_url": { "description": "Absolute http(s) URL that receives a POST for every item lifecycle change (feedback.item.created, .reopened, .confirmed) — the push half of the feedback loop, so an agent reacts to a report instead of polling for it. Delivery is best-effort with a 5 second timeout; the items list stays the source of truth. Set empty to turn push off.", "type": "string" }, "routes": { "description": "Where the widget appears, matched against the page path in the browser. `*` matches inside one path segment and `**` matches across segments, so /app/** covers /app/settings/billing. Start a pattern with ! to hide the widget there instead. An empty list shows it on every page you paste the script into. This decides where a button is drawn — it is not a security control, and the submit endpoint does not check it.", "items": { "description": "pattern", "type": "string" }, "type": "array" }, "theme": { "additionalProperties": true, "description": "How the button looks: accent (a colour like #2563eb), position (bottom-right, bottom-left, top-right, top-left) and label (the button text, up to 40 characters). The widget carries no MyAPI branding.", "type": "object" } }, "type": "object" } } }, "description": "Widget changes", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_FOUND", "INVALID_ROUTE", "TOO_MANY_ROUTES", "INVALID_THEME", "INVALID_CAPTURE", "INVALID_NOTIFY_URL", "INVALID_JSON", "RATE_LIMITED", "INVALID_REQUEST", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_FOUND` — No active widget with that id in this org.; `INVALID_ROUTE` — A route pattern does not start with / or is too long.; `TOO_MANY_ROUTES` — Over 50 route patterns.; `INVALID_THEME` — theme takes accent, position and label, and each has a fixed shape.; `INVALID_CAPTURE` — capture takes screenshot and text, each true or false, or null to restore the default.; `INVALID_NOTIFY_URL` — notify_url must be an absolute http or https URL, up to 2048 characters.; `INVALID_JSON` — The request body is not valid JSON.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Change a widget without minting a new key. Every field is optional and an omitted field keeps its value. `theme` and `capture` MERGE key by key, so setting one switch leaves the other alone and `null` deletes a key and restores its default — the same rule as PATCH container env. `routes` and `allowed_origins` are lists and REPLACE: send all of them, including the ones you are keeping. Changing routes takes effect in browsers within 5 minutes; you do not redeploy your site.", "tags": [ "feedback" ] } }, "/function/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of function: method, path, auth, params, error codes — public, no auth", "tags": [ "function" ] } }, "/function/orgs/{org_id}/functions": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Rows per page (1..500, default 50). Out-of-range values are rejected with 400 rather than clamped — a caller who asks for 5000 and silently gets 500 believes they have the whole list.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Keyset cursor — pass the previous page's meta.next_cursor. Absent on the last page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List functions for the org", "tags": [ "function" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "cron_schedule": { "description": "Required when trigger_type=cron; ignored otherwise", "type": "string" }, "name": { "description": "Kebab-case slug, 1-50 chars; reserved: www, api, admin, system, default", "type": "string" }, "scopes": { "description": "Optional slot allow-list for the minted key, e.g. [\"crm\",\"email\"]; empty = inherit the caller's grants", "type": "string" }, "trigger_type": { "description": "Trigger type", "enum": [ "http", "cron" ], "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "description": "Function creation payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NAME_TAKEN", "INVALID_TRIGGER", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NAME_TAKEN` — A function with that name already exists in this org. Pick another.; `INVALID_TRIGGER` — The trigger is not usable — see the message. Nothing was created.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a function. The scoped API key is returned ONCE in the response, and is also set on the deployed function as MYAPI_KEY (and __MYAPI_KEY) automatically, so you do not need to store or inject it yourself. It is org-locked (denied at /hq/*, /admin/*, /internal/*) and its slot grants are limited to the optional 'scopes' allow-list — the key is embedded in the function's Worker, so request only the slots it needs. Omitting scopes inherits the caller's grants; scopes can never exceed the caller's.", "tags": [ "function" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /function/orgs/{org_id}/functions/{id}", "reversible": true, "risk": "low" } } }, "/function/orgs/{org_id}/functions/{id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete a function (soft-delete + revoke scoped API key + tear down the deployed function)", "tags": [ "function" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } }, "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single function. invocations_total counts requests served at the edge, reconciled from the edge's usage figures on a delay (invocations_as_of says how far the count has read). Runs (GET .../runs) list workflow-triggered executions only.", "tags": [ "function" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } }, "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "cron_schedule": { "description": "New cron schedule (5-field cron). Valid only for a cron-triggered function.", "type": "string" } }, "required": [ "cron_schedule" ], "type": "object" } } }, "description": "Function config patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Update a cron function's schedule in place, without deleting and recreating it (which loses the function's URL, scoped key, and code). Only cron_schedule is patchable; name and trigger_type are fixed.", "tags": [ "function" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/function/orgs/{org_id}/functions/{id}/bundle": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "bundle_base64": { "description": "Base64 of the .js file. Same bytes as source; use it only when the code is already a file you did not author.", "type": "string" }, "bundle_ref": { "description": "upload_id of a staged upload, for a bundle too large to inline.", "type": "string" }, "source": { "description": "The JavaScript itself. Use this when you wrote the code and have it in hand — it is one ES module, and it is what deploy_function and the plan step expect.", "type": "string" } }, "type": "object" } }, "multipart/form-data": { "schema": { "properties": { "bundle": { "description": "The JavaScript bundle to deploy", "format": "binary", "type": "string" } }, "required": [ "bundle" ], "type": "object" } } }, "description": "The function bundle The function bundle, as JSON. Send exactly one of the three.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_FUNCTION_ID", "BUNDLE_REQUIRED", "BUNDLE_TOO_LARGE", "BUNDLE_READ_FAILED", "UPLOAD_NOT_FOUND", "CRON_NOT_SCHEDULED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_FUNCTION_ID` — The function id is not a valid id. Nothing was uploaded.; `BUNDLE_REQUIRED` — Send the JS bundle as the request body. Nothing was deployed.; `BUNDLE_TOO_LARGE` — The bundle is over the size cap. Nothing was deployed.; `BUNDLE_READ_FAILED` — The bundle could not be read. Send it again.; `UPLOAD_NOT_FOUND` — bundle_ref names no staged upload in this org, or its bytes were never PUT. Nothing was deployed.; `CRON_NOT_SCHEDULED` — The code was uploaded but its schedule could not be registered, so the function would never have run. It is NOT live — deploy again.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Deploy the function JS. Send the code itself as JSON in the source field — that is the usual way. bundle_base64, bundle_ref and the multipart field \"bundle\" also work. Wraps it with the MYAPI shim, uploads it to the edge runtime, rotates the scoped key, and returns the invocation_url. Your code reads the scoped key from the MYAPI_KEY environment variable — the same name a container uses — and we set it on every deploy, so it never goes stale. __MYAPI_KEY holds the same value and still works. Do NOT set MYAPI_KEY by hand: every deploy rotates the key, so a hand-set value silently stops working and the function answers 502 with nothing to point at. Returns status=provisioning with a ready_at hint: the URL 404s until the edge propagates (typically 4-45s), so poll it rather than redeploying.", "tags": [ "function" ], "x-safety": { "denylist": false, "disclosure": "live_site_change", "kind": "mutate", "proof": [ "http" ], "reversible": false, "risk": "high" } } }, "/function/orgs/{org_id}/functions/{id}/env": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "Secret name, e.g. STRIPE_KEY", "type": "string" }, "value": { "description": "Secret value", "type": "string" } }, "required": [ "name", "value" ], "type": "object" } } }, "description": "Env secret payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_DEPLOYED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_DEPLOYED` — The function has no deployed bundle yet. Upload one first: POST /function/orgs/{org_id}/functions/{id}/bundle; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Set a third-party secret on the function as an encrypted edge secret (encrypted at rest; never stored in MyAPI or returned).", "tags": [ "function" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/function/orgs/{org_id}/functions/{id}/runs": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Runs per page (1..500, default 50). Out-of-range values are rejected with 400 rather than clamped — a caller who asks for 5000 and silently gets 500 believes they have the whole list.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Keyset cursor — pass the previous page's meta.next_cursor. Absent on the last page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List recorded runs for the function, most recent first. IMPORTANT — this records workflow-triggered calls ONLY. A direct HTTP request to the invocation URL is served at the edge and is not recorded here, so an empty list does NOT mean the function was not called: a function serving hundreds of requests a day reports no runs if no workflow calls it. Use it to inspect workflow steps, not to prove whether the function ran.", "tags": [ "function" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/function/orgs/{org_id}/functions/{id}/scopes": { "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "scopes": { "description": "Slot names the function may call, for example [\"crm\",\"email\"]. This REPLACES the current list; include the slots you want to keep.", "items": { "type": "string" }, "type": "array" } }, "required": [ "scopes" ], "type": "object" } } }, "description": "New slot list — replaces the current one", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SCOPES_REQUIRED", "INVALID_SCOPES", "SCOPE_FORBIDDEN", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SCOPES_REQUIRED` — scopes named no slots. Nothing was changed.; `INVALID_SCOPES` — scopes named a slot that does not exist. Nothing was changed.; `SCOPE_FORBIDDEN` — The requested scopes are wider than the key making the change. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Change which slots a function may call, without recreating it. The function id and the invocation URL are unchanged, so every reference already handed out keeps working — previously the only way to add a slot was delete and recreate, which minted a new URL. The scoped key is replaced and pushed to the running function, so the change takes effect at once: a narrowing that left the old key alive would narrow nothing. Scopes can never exceed the grants of the key making the change. GET the function to see its current scopes.", "tags": [ "function" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/funnel/funnels/{id}/event": { "post": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "fields": { "additionalProperties": true, "description": "Arbitrary event payload", "type": "object" }, "label": { "description": "Event label", "type": "string" }, "pixel_id": { "description": "Pixel that observed the event", "type": "string" }, "section": { "description": "Page section the event fired in", "type": "string" }, "webhook": { "description": "Destination webhook slug", "type": "string" } }, "type": "object" } } }, "description": "Event", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Public funnel event ingest", "tags": [ "funnel" ] } }, "/funnel/funnels/{id}/submit/{slug}": { "post": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Public form-submission endpoint (lead capture; rate-limited)", "tags": [ "funnel" ] } }, "/funnel/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of funnel: method, path, auth, params, error codes — public, no auth", "tags": [ "funnel" ] } }, "/funnel/orgs/{org_id}/funnels": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List funnels for the org (currently 1 per org)", "tags": [ "funnel" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "favicon_url": { "description": "Public URL of the favicon", "type": "string" }, "global_style": { "additionalProperties": true, "description": "Style tokens applied across every page", "type": "object" }, "name": { "description": "Funnel name", "type": "string" }, "tracking": { "additionalProperties": true, "description": "Tracking / analytics configuration", "type": "object" } }, "required": [ "name" ], "type": "object" } } }, "description": "Funnel to create", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a funnel (rare; orgs auto-create one)", "tags": [ "funnel" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /funnel/orgs/{org_id}/funnels/{id}", "reversible": true, "risk": "low" } } }, "/funnel/orgs/{org_id}/funnels/{id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete a funnel + all its pages", "tags": [ "funnel" ], "x-safety": { "denylist": false, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } }, "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single funnel with metadata", "tags": [ "funnel" ] }, "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "favicon_url": { "description": "Public URL of the favicon.", "type": "string" }, "global_style": { "additionalProperties": true, "description": "Style tokens applied across every page.", "type": "object" }, "tracking": { "additionalProperties": true, "description": "Tracking / analytics configuration.", "type": "object" } }, "type": "object" } } }, "description": "Funnel config patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Update a funnel's config in place (favicon_url, global_style, tracking) without recreating it — the id, custom domain, and pages are kept. The name is the subdomain identity and is not changed here. Provide at least one field.", "tags": [ "funnel" ], "x-safety": { "denylist": false, "disclosure": "live_site_change", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/funnel/orgs/{org_id}/funnels/{id}/files": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "api_function_id": { "description": "Bind /api/* on this site to the given function", "type": "string" }, "env": { "description": "Publish channel (default prod)", "enum": [ "dev", "prod" ], "type": "string" }, "files": { "description": "One part per file; each part's filename is its path under the site root", "items": { "description": "File contents", "format": "binary", "type": "string" }, "type": "array" }, "spa_mode": { "description": "Serve index.html for unmatched paths. Defaults true when /index.html is present.", "type": "boolean" } }, "required": [ "files" ], "type": "object" } } }, "description": "The site files plus publish options", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLISH_RATE_LIMITED", "PUBLISH_TOO_LARGE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `PUBLISH_RATE_LIMITED` — Too many publishes in the last hour for this funnel or account. Nothing was published.; `PUBLISH_TOO_LARGE` — The upload is over the size cap. Nothing was published.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "v2 directory publish: multipart 'files' (one part per file, part filename = site path). Form fields: env (dev|prod), spa_mode (auto-true with /index.html), api_function_id (binds /api/* to a function). Records a manifest snapshot and moves the channel pointer.", "tags": [ "funnel" ], "x-safety": { "denylist": false, "disclosure": "live_site_change", "kind": "mutate", "proof": [ "http" ], "reversible": false, "risk": "high" } } }, "/funnel/orgs/{org_id}/funnels/{id}/forms": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Rows per page (1..500, default 50). Out-of-range values are rejected with 400 rather than clamped.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Keyset cursor — pass the previous page's meta.next_cursor. Absent on the last page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List all per-slug form bindings on a funnel.", "tags": [ "funnel" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "destination": { "description": "Destination as 'webhook:\u003cuuid\u003e' or 'workflow:\u003cuuid\u003e'.", "type": "string" }, "fields": { "description": "Optional array of {name, required?, oneof?, max_length?, regex?} for platform-side validation.", "type": "string" }, "honeypot_field": { "description": "Optional anti-bot field name; submissions populating it are silently dropped.", "type": "string" }, "rate_limit": { "description": "Optional {per_minute: \u003cint\u003e} cap per source IP.", "type": "string" }, "slug": { "description": "URL fragment the customer's \u003cform action\u003e targets (e.g. 'checkout').", "type": "string" } }, "required": [ "slug", "destination" ], "type": "object" } } }, "description": "Form binding", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SLUG_REQUIRED", "INVALID_SLUG", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SLUG_REQUIRED` — Send slug in the body. Nothing was created.; `INVALID_SLUG` — The slug is not usable — see the message. Nothing was created.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Register a per-slug form binding (destination + field validation + honeypot + rate-limit). Slug is unique per funnel; re-POST upserts.", "tags": [ "funnel" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/funnel/orgs/{org_id}/funnels/{id}/forms/{slug}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Remove a per-slug binding. Submissions to that slug fall back to funnel.org_webhook_id.", "tags": [ "funnel" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "POST /funnel/orgs/{org_id}/funnels/{id}/forms", "reversible": true, "risk": "low" } } }, "/funnel/orgs/{org_id}/funnels/{id}/pages": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Which channel to list — the live directory publish is per channel. Default prod.", "in": "query", "name": "env", "required": false, "schema": { "enum": [ "prod", "dev" ], "type": "string" } }, { "description": "Pass `true` to return each page's rendered content as well as its slug.", "in": "query", "name": "include_content", "required": false, "schema": { "type": "boolean" } }, { "description": "Rows per page (1..500, default 50). Out-of-range values are rejected with 400 rather than clamped.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Keyset cursor — pass the previous page's meta.next_cursor. Absent on the last page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List published page slugs, from BOTH publish paths: pages published one at a time, and every file in the live directory publish. Until 2026-08-23 it saw only the first, so a funnel published with a directory upload listed nothing while serving correctly.", "tags": [ "funnel" ] } }, "/funnel/orgs/{org_id}/funnels/{id}/pages/{slug}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_SLUG", "PUBLISH_FAILED", "KV_DELETE_FAILED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_SLUG` — The slug is not a usable page path — see the message. Nothing was removed.; `PUBLISH_FAILED` — The edge could not be updated to drop the page. Nothing was removed; retry.; `KV_DELETE_FAILED` — The edge could not delete the page object. Nothing was removed; retry.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Unpublish a single page (the reverse of push-page). The rest of the funnel — its id, custom domain, and other pages — stays live. 404 if no page is published at that slug.", "tags": [ "funnel" ], "x-safety": { "denylist": false, "disclosure": "live_site_change", "kind": "mutate", "reverse": "POST /funnel/orgs/{org_id}/funnels/{id}/push-page", "reversible": true, "risk": "high" } } }, "/funnel/orgs/{org_id}/funnels/{id}/push-page": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "html": { "description": "Full HTML body to serve. Use this for a page you are composing here.", "type": "string" }, "html_upload_id": { "description": "upload_id of a staged upload holding the page. Use this when the page already exists as a file: the bytes are published exactly as uploaded and never pass through a model. Stage with POST /storage/orgs/{org_id}/uploads/begin, PUT the bytes, then commit.", "type": "string" }, "slug": { "description": "Page path under the funnel domain (e.g. \"/\" or \"/pricing\")", "type": "string" }, "title": { "description": "HTML \u003ctitle\u003e", "type": "string" } }, "required": [ "slug" ], "type": "object" } } }, "description": "Page deploy payload. Send the HTML inline, or stage it and send html_upload_id.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SLUG_REQUIRED", "HTML_AMBIGUOUS", "UPLOAD_NOT_FOUND", "INVALID_SLUG", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SLUG_REQUIRED` — Send slug in the body. Nothing was published.; `HTML_AMBIGUOUS` — You sent both html and html_upload_id. Send one. Nothing was published.; `UPLOAD_NOT_FOUND` — html_upload_id names no staged upload in this org, or its bytes were never PUT. Nothing was published.; `INVALID_SLUG` — The slug is not usable — see the message. Nothing was published.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Publish a page to the edge (live)", "tags": [ "funnel" ], "x-safety": { "denylist": false, "disclosure": "live_site_change", "kind": "mutate", "proof": [ "screenshot", "http" ], "reverse": "POST /funnel/orgs/{org_id}/funnels/{id}/versions/{version_id}/restore", "reversible": true, "risk": "high" } } }, "/funnel/orgs/{org_id}/funnels/{id}/verify": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "html": { "description": "Full HTML body to validate", "type": "string" }, "slug": { "description": "Page path the HTML is intended for", "type": "string" } }, "required": [ "html" ], "type": "object" } } }, "description": "HTML to validate — nothing is published", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Validate funnel HTML against block + style rules", "tags": [ "funnel" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/funnel/orgs/{org_id}/funnels/{id}/versions": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Restrict the history to one page slug, e.g. /home.", "in": "query", "name": "slug", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_FOUND` — No funnel with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Page history, newest first. Every push-page appends a version (newest = live), so a bad edit can be undone. HTML is not included here — fetch a single version to read it. Filter to one page with ?slug.", "tags": [ "funnel" ] } }, "/funnel/orgs/{org_id}/funnels/{id}/versions/{version_id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "version_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_FOUND` — No version with that id for this funnel.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "One page version with its stored HTML, so you can preview it before restoring.", "tags": [ "funnel" ] } }, "/funnel/orgs/{org_id}/funnels/{id}/versions/{version_id}/restore": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "version_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_FOUND", "PUBLISH_FAILED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_FOUND` — No version with that id for this funnel.; `PUBLISH_FAILED` — The page could not be republished. Nothing was changed; retry.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Re-publish a prior version's HTML to its slug — the undo for push-page. The restored content becomes the newest version, so a restore is itself recorded and can be undone in turn.", "tags": [ "funnel" ], "x-safety": { "denylist": false, "disclosure": "live_site_change", "kind": "mutate", "proof": [ "http" ], "reverse": "POST /funnel/orgs/{org_id}/funnels/{id}/versions/{version_id}/restore", "reversible": true, "risk": "high" } } }, "/git/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of git: method, path, auth, params, error codes — public, no auth", "tags": [ "git" ] } }, "/git/orgs/{org_id}/repos": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Rows per page (1..500, default 50). Out-of-range values are rejected with 400 rather than clamped.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Keyset cursor — pass the previous page's meta.next_cursor. Absent on the last page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List repositories in the org.", "tags": [ "git" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "default_branch": { "description": "Default branch name (default 'main').", "type": "string" }, "name": { "description": "Repository name (^[a-zA-Z0-9][a-zA-Z0-9._-]{0,99}$).", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "description": "Repository create payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a git repository. Names match ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,99}$.", "tags": [ "git" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /git/orgs/{org_id}/repos/{repo}", "reversible": true, "risk": "low" } } }, "/git/orgs/{org_id}/repos/{repo}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete a repository and all its objects (irreversible). Returns 204.", "tags": [ "git" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } }, "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a repository's metadata (default branch, branch + tag counts).", "tags": [ "git" ] } }, "/git/orgs/{org_id}/repos/{repo}/blob/{ref}/{path}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "ref", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Read a file's contents at a ref. content_base64 holds the bytes.", "tags": [ "git" ] } }, "/git/orgs/{org_id}/repos/{repo}/branches": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "from": { "description": "Ref (branch, tag, or SHA) the branch starts at.", "type": "string" }, "name": { "description": "New branch name.", "type": "string" } }, "required": [ "name", "from" ], "type": "object" } } }, "description": "Branch create payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a branch pointing at a ref.", "tags": [ "git" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /git/orgs/{org_id}/repos/{repo}/branches/{branch}", "reversible": true, "risk": "low" } } }, "/git/orgs/{org_id}/repos/{repo}/branches/{branch}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "branch", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete a branch. Returns 204.", "tags": [ "git" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/git/orgs/{org_id}/repos/{repo}/commits": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "description": "Branch, tag or SHA to walk from (default HEAD).", "in": "query", "name": "ref", "required": false, "schema": { "type": "string" } }, { "description": "Commits to return (1..500, default 50). Out-of-range values are rejected with 400.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List commit history, newest first.", "tags": [ "git" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "author": { "description": "Commit author", "properties": { "email": { "description": "Author email.", "type": "string" }, "name": { "description": "Author name.", "type": "string" } }, "type": "object" }, "base": { "description": "Expected current branch tip SHA; empty = branch must not exist.", "type": "string" }, "branch": { "description": "Target branch name.", "type": "string" }, "changes": { "description": "File changes applied atomically. NOTE: the field is `changes`, not `files`. Each entry needs `path` and `content_base64` (or `content` for text).", "items": { "description": "A file change", "properties": { "content": { "description": "File content as inline text.", "type": "string" }, "content_base64": { "description": "File content base64-encoded (use for binary).", "type": "string" }, "delete": { "description": "Delete the file at path instead of writing it.", "type": "boolean" }, "mode": { "description": "File mode: 100644 (default), 100755 (exec), 120000 (symlink).", "type": "string" }, "path": { "description": "Repo-relative file path.", "type": "string" } }, "type": "object" }, "type": "array" }, "message": { "description": "Commit message.", "type": "string" } }, "required": [ "branch", "changes" ], "type": "object" } } }, "description": "Commit payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "UNKNOWN_FIELD", "PAYLOAD_TOO_LARGE", "UPLOAD_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `UNKNOWN_FIELD` — The request had a field the payload does not define (for example `files` — a commit's files go in `changes`). Nothing was committed.; `PAYLOAD_TOO_LARGE` — The request body is over the 16 MiB limit. Split a large commit into smaller ones, each chained on the previous tip via `base`. Nothing was committed.; `UPLOAD_NOT_FOUND` — A change's content_ref names no staged upload in this org, or its bytes were never PUT. Nothing was committed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Atomic multi-file commit. base is the expected current branch tip; an empty base means the branch must not yet exist. Returns 409 on a stale base.", "tags": [ "git" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/git/orgs/{org_id}/repos/{repo}/commits/{sha}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "sha", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single commit by SHA.", "tags": [ "git" ] } }, "/git/orgs/{org_id}/repos/{repo}/diff": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "description": "Ref to diff FROM. Required.", "in": "query", "name": "base", "required": true, "schema": { "type": "string" } }, { "description": "Ref to diff TO. Required.", "in": "query", "name": "head", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Unified diff between two refs.", "tags": [ "git" ] } }, "/git/orgs/{org_id}/repos/{repo}/merges": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "source": { "description": "Branch whose tip target fast-forwards to.", "type": "string" }, "target": { "description": "Branch to advance.", "type": "string" } }, "required": [ "target", "source" ], "type": "object" } } }, "description": "Merge payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Fast-forward merge source into target. Returns 422 when it is not a fast-forward.", "tags": [ "git" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/git/orgs/{org_id}/repos/{repo}/refs": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List all branches and tags.", "tags": [ "git" ] } }, "/git/orgs/{org_id}/repos/{repo}/repack": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Compact the repository's incremental packfiles into one (maintenance).", "tags": [ "git" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/git/orgs/{org_id}/repos/{repo}/tags": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "New tag name.", "type": "string" }, "ref": { "description": "Ref (branch, tag, or SHA) the tag points at.", "type": "string" } }, "required": [ "name", "ref" ], "type": "object" } } }, "description": "Tag create payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a lightweight tag pointing at a ref.", "tags": [ "git" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/git/orgs/{org_id}/repos/{repo}/tree/{ref}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "ref", "required": true, "schema": { "type": "string" } }, { "description": "Subdirectory to list. Omit for the repository root.", "in": "query", "name": "path", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List the directory tree at a ref (branch, tag, or SHA).", "tags": [ "git" ] } }, "/goal/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of goal: method, path, auth, params, error codes — public, no auth", "tags": [ "goal" ] } }, "/goal/orgs/{org_id}/goals": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List goals, open ones first, each with progress {current, target}.", "tags": [ "goal" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "outcome_id": { "description": "The outcome that created this goal, if any.", "type": "string" }, "predicate": { "description": "{event_kind, filter?: {payload.path: value}, count, distinct?: payload.path, deadline?: YYYY-MM-DD}", "properties": { "count": { "description": "How many matches achieve the goal (≥1).", "type": "integer" }, "deadline": { "description": "Events after this date do not count (RFC 3339 or YYYY-MM-DD).", "type": "string" }, "distinct": { "description": "Count distinct values of this payload field instead of events.", "type": "string" }, "event_kind": { "description": "The event that counts, e.g. payment.succeeded or schema.row.inserted.", "type": "string" }, "filter": { "additionalProperties": true, "description": "Equality filters on payload fields (dot paths).", "type": "object" } }, "type": "object" }, "statement": { "description": "The goal in plain words, e.g. \"first paying customer\".", "type": "string" } }, "required": [ "statement", "predicate" ], "type": "object" } } }, "description": "The goal", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "STATEMENT_REQUIRED", "PREDICATE_INVALID", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `STATEMENT_REQUIRED` — Send statement: the goal in plain words. Nothing was created.; `PREDICATE_INVALID` — The predicate is not usable — see the message. Nothing was created.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a goal: a plain-words statement plus the predicate that decides it — an event kind, optional equality filters on the event payload, a count target, an optional field to count DISTINCT values of (e.g. customer_id), and an optional deadline. Every real event of that kind advances it; test events never count. Reaching the target marks it achieved with the event attached and notifies the account owner.", "tags": [ "goal" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "POST /goal/orgs/{org_id}/goals/{id}/abandon", "reversible": true, "risk": "low" } } }, "/goal/orgs/{org_id}/goals/{id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "GOAL_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `GOAL_NOT_FOUND` — No goal with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Read one goal with its timeline of counted events — the attribution view; shown side by side with outcomes, never asserted as causality.", "tags": [ "goal" ] } }, "/goal/orgs/{org_id}/goals/{id}/abandon": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_OPEN", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_OPEN` — Only an open goal can be abandoned.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Stop tracking an open goal.", "tags": [ "goal" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Index of every service and its help URL — public, no auth", "tags": [ "help" ] } }, "/hq/account": { "delete": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Soft-delete the calling account. Deactivates all API keys; subsequent auth fails. Idempotent — DELETE on an already-deleted account still returns 204.", "tags": [ "hq" ] } }, "/hq/account/anonymous": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "description": "Optional email to attach at creation", "type": "string" }, "id_token": { "description": "Optional my-auth-api id_token (operator-login variant)", "type": "string" } }, "type": "object" } } }, "description": "Optional identity — omit the body entirely for a pure anonymous account", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create an anonymous account (no email; balance starts at $0 — the $5 credit grant lands when you upgrade: PATCH /hq/account/upgrade)", "tags": [ "hq" ] } }, "/hq/account/connections/google/confirm": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "challenge": { "description": "The link_challenge returned by the Google sign-in redirect", "type": "string" }, "code": { "description": "A two-factor code, if this account has two-factor on", "type": "string" }, "password": { "description": "The password already set on this account", "type": "string" } }, "required": [ "challenge", "password" ], "type": "object" } } }, "description": "The parked link, and proof of the existing credential", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "LINK_CHALLENGE_INVALID", "LINK_TOO_MANY_ATTEMPTS", "LINK_PROOF_INVALID", "CONNECTION_ALREADY_LINKED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `LINK_CHALLENGE_INVALID` — This link request has expired or was already used. Sign in with Google again to start over.; `LINK_TOO_MANY_ATTEMPTS` — Too many wrong passwords for this link request. Sign in with Google again to start over.; `LINK_PROOF_INVALID` — The password, or the two-factor code, did not match this account.; `CONNECTION_ALREADY_LINKED` — A google sign-in is already linked to this account.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Attach a Google sign-in to an existing account by proving the password it already has. Returned after a Google sign-in matches an account that has a password: the link waits until the owner proves it.", "tags": [ "hq" ] } }, "/hq/account/connections/google/confirm-email": { "get": { "parameters": [ { "description": "Single-use token from the confirmation email. Required.", "in": "query", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "LINK_CHALLENGE_INVALID", "CONNECTION_ALREADY_LINKED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `LINK_CHALLENGE_INVALID` — This link has expired or was already used. Sign in with Google again to start over.; `CONNECTION_ALREADY_LINKED` — A google sign-in is already linked to this account." } }, "summary": "Attach a Google sign-in to an existing PASSWORDLESS account by redeeming the single-use link mailed to the account's verified address. Returned to the mailbox after a Google sign-in matches an account with no password: the link waits until the mailbox owner confirms.", "tags": [ "hq" ] } }, "/hq/account/connections/{connection}": { "delete": { "parameters": [ { "in": "path", "name": "connection", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "UNKNOWN_CONNECTION", "CONNECTION_NOT_LINKED", "LAST_CONNECTION", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `UNKNOWN_CONNECTION` — The connection name is not one this account can remove. Only \"google\" can be removed; change a password with POST /hq/account/login.; `CONNECTION_NOT_LINKED` — No sign-in method of that kind is linked to this account, so there was nothing to remove.; `LAST_CONNECTION` — This is the only sign-in method on the account. Removing it would lock you out, so it was NOT removed. Set a password first: POST /hq/account/set-password.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Remove a sign-in method from the calling account. Only \"google\" can be removed today. Refuses when it is the only sign-in method left, and revokes the sessions that started through it.", "tags": [ "hq" ] } }, "/hq/account/create/key": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "grants": { "additionalProperties": true, "description": "Slot-\u003eaccess map, e.g. {\"email\":\"write\",\"crm\":\"read\"}; \"*\" grants all slots. Omit for unrestricted.", "type": "object" }, "name": { "description": "Human-readable label for the key", "type": "string" }, "org_id": { "description": "Lock the key to a single org; omit for account-wide", "type": "string" }, "spend_cap_cents": { "description": "Spend ceiling in cents, enforced over the key's lineage (this key and every key minted from it). 0 disallows spending; omit to inherit the caller's cap. Max 10000000 ($100000).", "type": "integer" } }, "required": [ "name" ], "type": "object" } } }, "description": "API key creation payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Mint a programmatic API key (returned once; SHA-256 stored). Capability IAM: optional grants (slot-\u003eread|write map, \"*\" = all), org_id (lock to one org), and spend_cap_cents. Omitted grants default to unrestricted. The requested authority must be a subset of the calling key's.", "tags": [ "hq" ] } }, "/hq/account/default-org": { "patch": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "org_id": { "description": "Org to make the default. Must belong to the calling account. null clears the preference.", "type": "string" } }, "type": "object" } } }, "description": "Default-org payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Pin the org that `login` hands back as default_org. Sticky across sessions and machines; org_id null clears it and reverts to the most recently created org.", "tags": [ "hq" ] } }, "/hq/account/delete/key/{id}": { "delete": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Revoke an API key (soft delete)", "tags": [ "hq" ] } }, "/hq/account/exchange": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "device": { "description": "Optional label for the machine signing in (e.g. a hostname). Names the minted key \"cli@\u003cdevice\u003e\" so `keys list` shows which machine holds which key. Omit for the plain \"cli\" name.", "type": "string" }, "id_token": { "description": "OIDC id_token minted by the MyAPI operator tenant on my-auth-api", "type": "string" } }, "required": [ "id_token" ], "type": "object" } } }, "description": "Exchange payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Exchange a my-auth-api id_token for an hq API key (operator login; public)", "tags": [ "hq" ] } }, "/hq/account/free-tier": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Return remaining free-tier allowances per service", "tags": [ "hq" ] } }, "/hq/account/keys": { "get": { "parameters": [ { "description": "Keys per page, 1-200. Default 50.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "meta.next_cursor from the previous page. Omit for the first page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Restrict to one key kind: function, manual, container or account.", "in": "query", "name": "kind", "required": false, "schema": { "type": "string" } }, { "description": "Only keys whose name starts with this, e.g. \"container:\".", "in": "query", "name": "name_prefix", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_LIMIT", "INVALID_CURSOR", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_LIMIT` — limit must be a whole number from 1 to 200.; `INVALID_CURSOR` — The cursor was not issued by this endpoint.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List active API keys for the calling account (raw key never returned; includes grants, org_id, kind, spend cap + current-period spend). Paged newest-first, 50 a page by default: an account accumulates keys fast because every function and container deploy mints one, and returning all of them made this endpoint unusable for an agent client. Filter with kind or name_prefix rather than walking every page. When meta.has_more is true, pass meta.next_cursor back as ?cursor=. current_period_spend_cents is summed over the key's LINEAGE, not this key alone, so every key in a family reports the same figure — it matches how the cap is enforced.", "tags": [ "hq" ] } }, "/hq/account/keys/revoke-all": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "kind": { "description": "Restrict to one key kind", "enum": [ "function", "manual", "account" ], "type": "string" } }, "type": "object" } } }, "description": "Revoke-all payload (kind optional)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Kill switch — revoke every active API key in the account. Optional kind filter ('function' | 'manual' | 'account') narrows it. Revoking all includes the caller's own key; recovery is re-auth via login.", "tags": [ "hq" ] } }, "/hq/account/keys/{id}/usage": { "get": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_REQUEST", "RATE_LIMITED", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_REQUEST` — The key id is missing.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "What this key has actually called: one row per service, with a call count and first/last dates, plus suggested_grants — the grant map covering exactly those services. This is what makes narrowing a key an observation instead of a guess: reading your own source finds the calls you remember, and the platform's own runtime helpers call services you never wrote. It reports what was SEEN, so a code path never taken does not appear — read it over a period covering your whole application, mint the narrower key, run against it, then revoke the wide one. An empty list returns no suggestion at all: it means the key is unused OR is not the one your code holds, and narrowing on that would produce a key that can do nothing.", "tags": [ "hq" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/hq/account/login": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "description": "", "type": "string" }, "password": { "description": "", "type": "string" } }, "required": [ "email", "password" ], "type": "object" } } }, "description": "Login payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Email + password login; returns JWT + refresh token", "tags": [ "hq" ] } }, "/hq/account/mailing-address": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Current mailing address", "properties": { "mailing_address": { "description": "Physical postal address, or null when unset.", "type": "string" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Return the account's current mailing address (null when unset). Read counterpart to PATCH /hq/account/mailing-address.", "tags": [ "hq" ] }, "patch": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "mailing_address": { "description": "Physical postal address, e.g. '123 Main St, Springfield, IL 62701, USA'.", "type": "string" } }, "required": [ "mailing_address" ], "type": "object" } } }, "description": "Mailing address", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Set the account's mailing address (required for transactional email — appended to outbound bodies for CAN-SPAM).", "tags": [ "hq" ] } }, "/hq/account/me": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Return the calling account (id, email, type, balance, spend cap + current-period spend)", "tags": [ "hq" ] } }, "/hq/account/mfa": { "delete": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The 6-digit code currently shown by the app, or a recovery code", "type": "string" } }, "required": [ "code" ], "type": "object" } } }, "description": "A code from the authenticator app", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MFA_NOT_ENABLED", "MFA_CODE_INVALID", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MFA_NOT_ENABLED` — Two-factor authentication is not on for this account.; `MFA_CODE_INVALID` — That code is not right. A current code is required to turn two-factor off.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Turn two-factor off. Requires a current code, so a stolen session cannot switch it off.", "tags": [ "hq" ] } }, "/hq/account/mfa/confirm": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The 6-digit code currently shown by the app", "type": "string" } }, "required": [ "code" ], "type": "object" } } }, "description": "A code from the authenticator app", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MFA_NOT_STARTED", "MFA_ALREADY_ENABLED", "MFA_CODE_INVALID", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MFA_NOT_STARTED` — No two-factor setup is in progress. Call POST /hq/account/mfa/setup first.; `MFA_ALREADY_ENABLED` — Two-factor authentication is already on for this account.; `MFA_CODE_INVALID` — That code is not right. Use the code the authenticator shows now.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Turn two-factor on by proving you can generate a code. Returns single-use recovery codes, which are not shown again.", "tags": [ "hq" ] } }, "/hq/account/mfa/setup": { "post": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MFA_ALREADY_ENABLED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MFA_ALREADY_ENABLED` — Two-factor authentication is already on for this account. Turn it off before setting it up again.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Start two-factor setup. Returns a TOTP secret and an otpauth:// URI to scan. Does NOT turn it on — confirm a code first.", "tags": [ "hq" ] } }, "/hq/account/mfa/verify": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "challenge": { "description": "The challenge returned by POST /hq/account/login", "type": "string" }, "code": { "description": "The 6-digit code from the authenticator, or a recovery code", "type": "string" } }, "required": [ "challenge", "code" ], "type": "object" } } }, "description": "The challenge from login, and a code", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MFA_CHALLENGE_INVALID", "MFA_TOO_MANY_ATTEMPTS", "MFA_CODE_INVALID", "MFA_NOT_ENABLED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MFA_CHALLENGE_INVALID` — This sign-in attempt has expired or was already used. Sign in again.; `MFA_TOO_MANY_ATTEMPTS` — Too many wrong codes for this sign-in attempt. Sign in again.; `MFA_CODE_INVALID` — That code is not right. Use the current code, or a recovery code.; `MFA_NOT_ENABLED` — Two-factor authentication is not on for this account.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Finish a sign-in that returned mfa_required. Exchanges the challenge plus a code for a session.", "tags": [ "hq" ] } }, "/hq/account/promo": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The promotional code, e.g. XF26. Case and surrounding spaces are ignored.", "type": "string" } }, "required": [ "code" ], "type": "object" } } }, "description": "The code", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "PROMO_CODE_REQUIRED", "PROMO_NOT_FOUND", "PROMO_EXPIRED", "PROMO_ALREADY_REDEEMED", "PROMO_EXHAUSTED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `PROMO_CODE_REQUIRED` — No code was sent. Nothing was credited.; `PROMO_NOT_FOUND` — No such code. Nothing was credited — check the spelling.; `PROMO_EXPIRED` — The code has expired. Nothing was credited.; `PROMO_ALREADY_REDEEMED` — This account already redeemed this code. It was NOT credited again.; `PROMO_EXHAUSTED` — The code has been fully claimed. Nothing was credited.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Redeem a promotional code for account credits. Credits are spent BEFORE your balance and cannot pay for a domain registration — everything else on the platform accepts them. A code works once per account, and the refusals tell apart the three ways it can fail: the code is unknown, it has expired, or this account already used it. The code is matched without regard to case or surrounding spaces.", "tags": [ "hq" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/hq/account/refresh": { "post": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MISSING_REFRESH_TOKEN", "INVALID_REFRESH_TOKEN", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MISSING_REFRESH_TOKEN` — Send refresh_token in the body.; `INVALID_REFRESH_TOKEN` — The refresh token is not valid. Sign in again.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Exchange a refresh token for a new JWT", "tags": [ "hq" ] } }, "/hq/account/register": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "description": "Account email; must not already be registered", "type": "string" }, "password": { "description": "Min 12 chars", "type": "string" } }, "required": [ "email", "password" ], "type": "object" } } }, "description": "Registration payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "EMAIL_TAKEN", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `EMAIL_TAKEN` — An account with this email already exists. Sign in instead.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Register a new human account by email + password (sends verification email)", "tags": [ "hq" ] } }, "/hq/account/resume-sending": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "org_id": { "description": "Resume only this organisation. Omit to resume everything that is back within its limits.", "type": "string" } }, "type": "object" } } }, "description": "Optional scope", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "STILL_OVER_THRESHOLD", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `STILL_OVER_THRESHOLD` — The last 24 hours are still over the limit. The numbers are in the response.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Turn sending back on after an automatic pause. Pauses have two tiers. The platform pauses ONE organisation when too much of that organisation's recent mail bounces or is marked spam; the other organisations keep sending. It pauses the whole account only at a higher bar, for mail no organisation explains. This lifts a pause when the last 24 hours are back within the limits — so fix the list first. Send org_id to resume one organisation; send no body to resume every organisation that is back within its limits, then the account. The refusal carries the CURRENT numbers. Safe to call when nothing is paused: it says so and changes nothing.", "tags": [ "hq" ] } }, "/hq/account/send-code": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "description": "Address to send the 6-digit code to", "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "description": "Code request", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_EMAIL", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_EMAIL` — The email is not a valid address.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Send a 6-digit code for code-based CLI auth (public)", "tags": [ "hq" ] } }, "/hq/account/sending": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Whether this account can send email, and how close it is to the limits — sends, bounces and complaints over the last 24 hours, against the thresholds. Read this rather than the pause message: the pause message is a record of when it was set, and these numbers are from now.", "tags": [ "hq" ] } }, "/hq/account/set-password": { "post": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "PASSWORD_ALREADY_SET", "ACCOUNT_ANONYMOUS", "EMAIL_UNVERIFIED", "TOO_MANY_REQUESTS", "EMAIL_ERROR", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `PASSWORD_ALREADY_SET` — The account already has a password, so no email was sent. Changing a password is not supported yet — contact support.; `ACCOUNT_ANONYMOUS` — The account has no real email, so no email was sent. Attach one first: PATCH /hq/account/upgrade.; `EMAIL_UNVERIFIED` — The account email is not verified, so no email was sent. Verify it first: POST /hq/account/send-code, then POST /hq/account/verify-code.; `TOO_MANY_REQUESTS` — A set-password email was sent less than a minute ago, so no new email was sent. Wait a minute, then retry.; `EMAIL_ERROR` — The email could not be sent, so no set-password token exists. Retry.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Start setting a first password on an account that has none (google-only, or code-based). Sends a single-use token to the account's verified email; confirm with POST /hq/account/set-password/confirm. Refuses when the account already has a password, is anonymous, or its email is not verified.", "tags": [ "hq" ] } }, "/hq/account/set-password/confirm": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "password": { "description": "New password, min 12 chars", "type": "string" }, "token": { "description": "The single-use token from the set-password email", "type": "string" } }, "required": [ "token", "password" ], "type": "object" } } }, "description": "The emailed token, and the new password", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SET_PASSWORD_TOKEN_INVALID", "PASSWORD_TOO_SHORT", "PASSWORD_ALREADY_SET" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SET_PASSWORD_TOKEN_INVALID` — The token is wrong, expired or already used, so no password was set. Request a new one: POST /hq/account/set-password.; `PASSWORD_TOO_SHORT` — The password must be at least 12 characters, so no password was set.; `PASSWORD_ALREADY_SET` — The account already has a password, so nothing was changed." } }, "summary": "Finish setting a first password: exchange the emailed single-use token plus the new password (min 12 chars). Public — the token is the authentication.", "tags": [ "hq" ] } }, "/hq/account/spend-cap": { "patch": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "period": { "description": "Window the cap applies over", "enum": [ "month", "day", "none" ], "type": "string" }, "spend_cap_cents": { "description": "Cap in cents for the period; null clears the cap", "type": "integer" } }, "type": "object" } } }, "description": "Spend-cap payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Set or clear the account-level spend ceiling (Layer 2). spend_cap_cents null clears the cap.", "tags": [ "hq" ] } }, "/hq/account/upgrade": { "patch": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "description": "Email address to attach to the anonymous account", "type": "string" }, "id_token": { "description": "A my-auth-api id_token; upgrades via the operator-login flow instead of email", "type": "string" } }, "type": "object" } } }, "description": "Upgrade payload — supply either email (classic) or id_token (operator login)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_ANONYMOUS", "INVALID_EMAIL", "EMAIL_TAKEN", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_ANONYMOUS` — The account already has an email. Nothing was changed.; `INVALID_EMAIL` — The email is not a valid address.; `EMAIL_TAKEN` — An account with this email already exists.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Upgrade an anonymous account: attach an email or a my-auth-api id_token. Grants the $5 starter credits once.", "tags": [ "hq" ] } }, "/hq/account/verify-code": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The 6-digit code", "type": "string" }, "email": { "description": "The address the code was sent to", "type": "string" } }, "required": [ "email", "code" ], "type": "object" } } }, "description": "Code exchange", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MFA_REQUIRED", "TOO_MANY_ATTEMPTS", "INVALID_CODE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MFA_REQUIRED` — This account uses two-factor authentication. Send the current code from the authenticator app as mfa_code.; `TOO_MANY_ATTEMPTS` — Too many wrong two-factor codes for this sign-in. Request a new code with POST /hq/account/send-code.; `INVALID_CODE` — The code is wrong or expired. Get a new one: POST /hq/account/send-code; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Exchange the emailed one-time code for an API key. If the account uses two-factor, send mfa_code as well.", "tags": [ "hq" ] } }, "/hq/account/verify-email": { "get": { "parameters": [ { "description": "Single-use token from the registration email. Required.", "in": "query", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "TOKEN_EXPIRED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `TOKEN_EXPIRED` — The verification link expired. Register again to get a new one.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Verify a registration via the link sent by /register.", "tags": [ "hq" ] } }, "/hq/auth/google/callback": { "get": { "parameters": [ { "description": "Authorization code returned by Google.", "in": "query", "name": "code", "required": false, "schema": { "type": "string" } }, { "description": "Opaque state echoed back by Google; verified before use.", "in": "query", "name": "state", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "ACCOUNT_EMAIL_UNVERIFIED", "EMAIL_ERROR", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `ACCOUNT_EMAIL_UNVERIFIED` — An account with this email exists but its email is not verified, so the Google sign-in was NOT linked. Verify the email first: POST /hq/account/send-code, then POST /hq/account/verify-code.; `EMAIL_ERROR` — The confirmation email could not be sent, so the Google sign-in was NOT linked. Retry.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Google OAuth callback; issues a JWT and redirects to the dashboard. When the email matches an existing account, NO merge happens on the match alone: a password-holding account parks the link behind a password challenge, a passwordless verified-email account parks it behind a confirmation link mailed to that address, and an unverified-email account refuses.", "tags": [ "hq" ] } }, "/hq/auth/google/redirect": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Begin Google OAuth flow; redirects to Google", "tags": [ "hq" ] } }, "/hq/billing/auto-recharge": { "delete": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Disable auto-recharge (keeps the saved numbers for easy re-enable)", "tags": [ "hq" ] }, "get": { "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Auto-recharge state", "properties": { "amount_cents": { "description": "Amount charged per refill (null if unset)", "type": "integer" }, "enabled": { "description": "Whether auto-recharge is on", "type": "boolean" }, "has_payment_method": { "description": "Whether a card is saved", "type": "boolean" }, "last_recharge_attempt_at": { "description": "RFC3339 timestamp of the last attempt (null if never)", "type": "string" }, "last_recharge_status": { "description": "'succeeded'|'failed'|'capped'|'no_pm'|'pending' (null if never attempted)", "type": "string" }, "month_to_date_recharged_cents": { "description": "Auto-recharged so far this month", "type": "integer" }, "monthly_cap_cents": { "description": "Max auto-recharged per calendar month (null if unset)", "type": "integer" }, "threshold_cents": { "description": "Balance below which a refill triggers (null if unset)", "type": "integer" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Return auto-recharge config, last status, and month-to-date auto-recharged total", "tags": [ "hq" ] }, "put": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "amount_cents": { "description": "Amount to charge per refill (required when enabling)", "type": "integer" }, "enabled": { "description": "Turn auto-recharge on or off", "type": "boolean" }, "monthly_cap_cents": { "description": "Max auto-recharged per calendar month (required when enabling)", "type": "integer" }, "threshold_cents": { "description": "Balance below which a refill triggers (required when enabling)", "type": "integer" } }, "required": [ "enabled" ], "type": "object" } } }, "description": "Auto-recharge config", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Enable/update auto-recharge. Enabling requires a saved card; amount_cents ≥ floor ($5) and ≥ threshold_cents; monthly_cap_cents ≥ amount_cents.", "tags": [ "hq" ] } }, "/hq/billing/balance": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "ACCOUNT_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `ACCOUNT_NOT_FOUND` — No such account.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Return account balance (paid + credits) and payment-method state", "tags": [ "hq" ] } }, "/hq/billing/history": { "get": { "parameters": [ { "description": "Rows per page (1..500, default 50). Out-of-range values are rejected with 400 rather than clamped.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Keyset cursor — pass the previous page's meta.next_cursor. It is the composite `source:id` of the last row (source is `stripe` or `usage`), because this list unions two tables and no single id spans both.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Return billing-event history for the account (top-ups and usage charges, newest first)", "tags": [ "hq" ] } }, "/hq/billing/setup-payment": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "payment_method_id": { "description": "Stripe PaymentMethod id (pm_…)", "type": "string" } }, "type": "object" } } }, "description": "Payment method", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Begin Stripe SetupIntent for a payment method", "tags": [ "hq" ] } }, "/hq/billing/setup-payment/confirm": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "payment_method_id": { "description": "Stripe PaymentMethod id (pm_…) to confirm", "type": "string" } }, "type": "object" } } }, "description": "Payment method", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Confirm a Stripe SetupIntent", "tags": [ "hq" ] } }, "/hq/billing/topup": { "post": { "parameters": [ { "description": "Retry-safety token. Sending the same key within 24h returns the original response without re-charging the card. Use a fresh UUID per logical operation; same UUID for any retry of that operation.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "amount_dollars": { "description": "Whole-dollar amount to add to the account balance (max 100).", "type": "integer" } }, "required": [ "amount_dollars" ], "type": "object" } } }, "description": "Top-up payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NO_PAYMENT_METHOD", "INVALID_AMOUNT", "PAYMENT_FAILED", "CHECKOUT_FAILED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NO_PAYMENT_METHOD` — No saved payment method on this account, so nothing was charged. Add one in the billing portal first.; `INVALID_AMOUNT` — The amount is outside the allowed range. Nothing was charged.; `PAYMENT_FAILED` — The payment was declined. Nothing was added to the balance.; `CHECKOUT_FAILED` — A checkout session could not be started. Nothing was charged.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Charge a top-up via Stripe PaymentIntent. Supports Idempotency-Key header for retry safety (24h TTL).", "tags": [ "hq" ] } }, "/hq/billing/usage": { "get": { "parameters": [ { "description": "Rollup window (default month).", "in": "query", "name": "period", "required": false, "schema": { "enum": [ "month", "30d" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Return spend rolled up by service.", "tags": [ "hq" ] } }, "/hq/billing/webhook": { "post": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Stripe webhook receiver (public, signature-verified)", "tags": [ "hq" ] } }, "/hq/connections": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List the apps connected to this account through the connect flow: which app, when it connected, when it was last used, which organizations it may act on (all, or a list), and its monthly spend cap. The raw token is never returned.", "tags": [ "hq" ] } }, "/hq/connections/{id}": { "delete": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_FOUND` — No connection with that id in this account.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Revoke one connection. Its next call is refused and its refresh chain is dead. Returns 204.", "tags": [ "hq" ] }, "patch": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "cap_dollars": { "description": "Monthly spend cap in whole US dollars, 0 to 1000000.", "type": "integer" }, "scope": { "description": "{all: true} for every organization in the account, now and later; or {org_ids: [...]} to limit it to those.", "properties": {}, "type": "object" } }, "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "CONNECTION_CANNOT_EDIT_ITSELF", "ORG_NOT_FOUND", "NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `CONNECTION_CANNOT_EDIT_ITSELF` — The caller is a connection. A connection cannot change what connections may do. Nothing was changed. Sign in to the account and change it there.; `ORG_NOT_FOUND` — One or more org_ids are not in this account. Nothing was changed.; `NOT_FOUND` — No connection with that id in this account.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Change what one connection may do: the organizations it acts on (scope {all: true}, or {org_ids: [...]}) and/or its monthly cap (cap_dollars). Takes effect on the connection's next call; nothing reconnects. A connection cannot change itself — sign in to the account to change it.", "tags": [ "hq" ] } }, "/hq/healthz": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Liveness probe (no diagnostic depth — see /ops/status)", "tags": [ "hq" ] } }, "/hq/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of hq: method, path, auth, params, error codes — public, no auth", "tags": [ "hq" ] } }, "/hq/limits": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "The rate limits this platform enforces, per service. Each is per ACCOUNT per minute — shared by every API key and every browser session on that account, so a test harness and a human's open tab draw on one budget. Burst equals the per-minute rate. Exceeding one answers 429 with code RATE_LIMITED, a Retry-After header, and the limit that was hit. Services absent from this list are not rate limited. Public: a limit you must authenticate to read is one you discover by being refused.", "tags": [ "hq" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/hq/org-imports": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "auto_accept": { "description": "Skip the confirm step and create the org as soon as the scrape finishes", "type": "boolean" }, "domain": { "description": "Domain to scrape branding from", "type": "string" }, "org_id": { "description": "Import into this existing org instead of creating one", "type": "string" } }, "required": [ "domain" ], "type": "object" } } }, "description": "Import source", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Kick off an async org-import job (scrape brand from URL)", "tags": [ "hq" ] } }, "/hq/org-imports/{job_id}": { "get": { "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get import job status + scraped brand JSON", "tags": [ "hq" ] } }, "/hq/org-imports/{job_id}/confirm": { "post": { "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "business_sector": { "description": "Industry / sector", "type": "string" }, "canonical_url": { "description": "Canonical site URL", "type": "string" }, "color_palette": { "additionalProperties": true, "description": "Brand colors keyed by role (primary, accent, background, …)", "type": "object" }, "cookie_policy_url": { "description": "Cookie policy URL", "type": "string" }, "cta_text": { "description": "Primary call-to-action label", "type": "string" }, "default_language": { "description": "BCP-47 language tag (e.g. \"en\")", "type": "string" }, "description": { "description": "Longer description of the business", "type": "string" }, "favicon_url": { "description": "Public URL of the favicon", "type": "string" }, "font_family": { "description": "Primary font family", "type": "string" }, "gdpr_enabled": { "description": "Show the GDPR consent banner on published pages", "type": "boolean" }, "headline": { "description": "Hero headline", "type": "string" }, "imagery_style": { "description": "Art direction for generated imagery", "type": "string" }, "logo_url": { "description": "Public URL of the logo", "type": "string" }, "name": { "description": "Override the scraped org name", "type": "string" }, "og_image_url": { "description": "Public URL of the Open Graph share image", "type": "string" }, "onboarding_step": { "description": "Where the org is in onboarding", "type": "string" }, "privacy_policy_url": { "description": "Privacy policy URL", "type": "string" }, "social_links": { "additionalProperties": true, "description": "Social profile URLs keyed by network", "type": "object" }, "subheadline": { "description": "Hero subheadline", "type": "string" }, "tagline": { "description": "Short positioning line", "type": "string" }, "terms_url": { "description": "Terms of service URL", "type": "string" }, "tracking": { "additionalProperties": true, "description": "Tracking / analytics configuration", "type": "object" }, "value_propositions": { "description": "Selling points", "items": { "description": "A single value proposition", "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Optional overrides applied on top of the scraped brand before the org is created", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Confirm import; creates the org from the scraped brand", "tags": [ "hq" ] } }, "/hq/orgs": { "get": { "parameters": [ { "description": "archived, test, or all — what to show beyond active organisations", "in": "query", "name": "include", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List the account's organisations. Archived and test organisations are left out unless the query says include=archived,test. The org an omitted org_id resolves to is marked default: true.", "tags": [ "hq" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "business_sector": { "description": "e.g. \"hospitality\", \"saas\", \"beauty\"", "type": "string" }, "description": { "description": "Optional description", "type": "string" }, "is_test": { "description": "Make this a test organisation: hidden from lists by default and never counted in your numbers. Set at creation only.", "type": "boolean" }, "name": { "description": "Display name", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "description": "Org creation payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create an organisation (auto-creates a funnel + KV mapping)", "tags": [ "hq" ] } }, "/hq/orgs/{id}": { "delete": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "The confirm_token from the refusal, or the org id again, to confirm a destructive delete. Required only when the org still owns resources.", "in": "query", "name": "confirm", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "CONFIRM_REQUIRED", "CONFIRM_EXPIRED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `CONFIRM_REQUIRED` — The org still owns resources and the delete was NOT performed. The message lists what would be destroyed and carries a single-use confirm_token (10 minutes). Repeat with ?confirm=\u003cconfirm_token\u003e.; `CONFIRM_EXPIRED` — The confirm token has expired or was already used and the delete was NOT performed. Repeat the call without ?confirm to get a new token.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete an org and everything underneath it — containers, domains, mailboxes, database namespaces, funnels, CRM data and keys. This is permanent and cannot be undone. An org that still owns any of those is REFUSED with CONFIRM_REQUIRED, listing what it holds and carrying a single-use confirm_token; repeat the call with ?confirm=\u003cconfirm_token\u003e (or ?confirm=\u003corg_id\u003e) to go ahead. An empty org deletes without confirmation.", "tags": [ "hq" ] }, "get": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single org with all branding fields", "tags": [ "hq" ] }, "patch": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "business_sector": { "description": "Industry / sector", "type": "string" }, "canonical_url": { "description": "Canonical site URL", "type": "string" }, "color_palette": { "additionalProperties": true, "description": "Brand colors keyed by role (primary, accent, background, …)", "type": "object" }, "cookie_policy_url": { "description": "Cookie policy URL", "type": "string" }, "cta_text": { "description": "Primary call-to-action label", "type": "string" }, "default_language": { "description": "BCP-47 language tag (e.g. \"en\")", "type": "string" }, "description": { "description": "Longer description of the business", "type": "string" }, "favicon_url": { "description": "Public URL of the favicon", "type": "string" }, "font_family": { "description": "Primary font family", "type": "string" }, "gdpr_enabled": { "description": "Show the GDPR consent banner on published pages", "type": "boolean" }, "headline": { "description": "Hero headline", "type": "string" }, "imagery_style": { "description": "Art direction for generated imagery", "type": "string" }, "is_test": { "description": "Mark the org a test organisation, or clear the mark. A test org is hidden from GET /hq/orgs unless you ask for it with ?include=test. Settable after create, so an org made before this existed can still be filed away.", "type": "boolean" }, "logo_url": { "description": "Public URL of the logo", "type": "string" }, "name": { "description": "Org display name", "type": "string" }, "og_image_url": { "description": "Public URL of the Open Graph share image", "type": "string" }, "onboarding_step": { "description": "Where the org is in onboarding", "type": "string" }, "privacy_policy_url": { "description": "Privacy policy URL", "type": "string" }, "social_links": { "additionalProperties": true, "description": "Social profile URLs keyed by network", "type": "object" }, "subheadline": { "description": "Hero subheadline", "type": "string" }, "tagline": { "description": "Short positioning line", "type": "string" }, "terms_url": { "description": "Terms of service URL", "type": "string" }, "tracking": { "additionalProperties": true, "description": "Tracking / analytics configuration", "type": "object" }, "value_propositions": { "description": "Selling points", "items": { "description": "A single value proposition", "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Any combination of branding fields — omitted fields are left untouched", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Update an org: its branding fields, or is_test to file it away as a sandbox.", "tags": [ "hq" ] } }, "/hq/orgs/{id}/archive": { "post": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "ORG_NOT_FOUND", "ORG_HAS_LIVE_RESOURCES", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `ORG_NOT_FOUND` — No organisation with that id in this account.; `ORG_HAS_LIVE_RESOURCES` — The organisation still runs something that costs money or serves traffic. The message names it. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Archive an organisation: it leaves every list and stays exactly as it is — nothing is deleted, its routes keep working, unarchive brings it back. Refused while it still runs containers, functions or live domains.", "tags": [ "hq" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "POST /hq/orgs/{id}/unarchive", "reversible": true, "risk": "low" } } }, "/hq/orgs/{id}/spend-cap": { "patch": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "spend_cap_cents": { "description": "Ceiling in cents (0 to 10000000). 0 disallows spending; null removes the cap.", "type": "integer" }, "spend_cap_period": { "description": "Window the cap resets over: month (default), day, or none.", "type": "string" } }, "required": [ "spend_cap_cents" ], "type": "object" } } }, "description": "The org spend ceiling", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_SPEND_CAP", "NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_SPEND_CAP` — spend_cap_cents was out of range (0..10000000). Nothing was changed.; `NOT_FOUND` — No org with that id in this account. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Set or remove a per-org spend ceiling. Below the account cap and above each key's own cap, this bounds total spend within one org, so a runaway agent in one org cannot drain the account against every other org. Off by default; set spend_cap_cents to turn it on, or null to remove it.", "tags": [ "hq" ] } }, "/hq/orgs/{id}/unarchive": { "post": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "ORG_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `ORG_NOT_FOUND` — No organisation with that id in this account.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Bring an archived organisation back into the lists.", "tags": [ "hq" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/hq/orgs/{org_id}/doctor": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Org-wide consistency report", "properties": { "cache_ttl_seconds": { "description": "How long the server may cache this report", "type": "integer" }, "generated_at": { "description": "RFC3339 timestamp", "type": "string" }, "org_id": { "description": "The org this report covers", "type": "string" }, "sections": { "description": "Section reports, in canonical order", "items": { "description": "One section of the report", "properties": { "issues": { "description": "All findings in this section", "items": { "description": "One health-check finding", "properties": { "category": { "description": "reference_integrity | orphan | activity | security | billing | internal", "type": "string" }, "entity": { "description": "Optional resource pointer for deep links", "properties": { "id": { "description": "Resource id", "type": "string" }, "name": { "description": "Human label", "type": "string" }, "slot": { "description": "Resource slot (funnel, webhook, workflow, …)", "type": "string" } }, "type": "object" }, "hint": { "description": "Customer-actionable remediation guidance, when available. Absent on operator-only issues.", "type": "string" }, "id": { "description": "Stable dedupable id, e.g. webhook-orphan/abc1234", "type": "string" }, "message": { "description": "Customer-facing description. Self-contained; never references internal paths/tickets/providers.", "type": "string" }, "operator_only": { "description": "True when this is a platform-side issue the customer cannot action (our infra/secrets). Clients may hide it or render a generic 'degraded' note; the operator detail is logged server-side, not included here.", "type": "boolean" }, "scope": { "description": "Logical scope, e.g. funnel/example.com", "type": "string" }, "severity": { "description": "Issue severity", "enum": [ "ok", "warn", "crit" ], "type": "string" } }, "type": "object" }, "type": "array" }, "name": { "description": "Section name (funnels, webhooks, workflows, …)", "type": "string" }, "resource_count": { "description": "Authoritative count of resources of this section's kind in the org (0 when none). Use this — not issues.length — to tell 'no resources' from 'present and healthy'.", "type": "integer" }, "summary": { "description": "One-line section summary", "type": "string" } }, "type": "object" }, "type": "array" }, "totals": { "description": "Issue counts by severity", "properties": { "crit": { "description": "Critical findings", "type": "integer" }, "ok": { "description": "OK-level findings", "type": "integer" }, "warn": { "description": "Warning findings", "type": "integer" } }, "type": "object" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Org consistency report — sections of issues by severity. Optional ?sections=funnels,webhooks to scope.", "tags": [ "hq" ] } }, "/hq/pricing": { "get": { "parameters": [ { "description": "Return only keys starting with this, for example \"email.\" or \"container.\". Absent returns every price.", "in": "query", "name": "prefix", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "What every billable operation costs, in cents. Prices were previously readable only by operators, so nothing a customer or agent could call knew them — the only way to learn a price was to be charged it, and an account too low to complete a sequence learned only the cheapest step's price before stopping. Filter with ?prefix=email. to answer one service's costs without reading the whole list.", "tags": [ "hq" ] } }, "/image/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of image: method, path, auth, params, error codes — public, no auth", "tags": [ "image" ] } }, "/image/orgs/{org_id}/generate": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "aspect_ratio": { "description": "", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4" ], "type": "string" }, "colors": { "description": "Optional palette hint", "type": "string" }, "has_text": { "description": "Whether the image should include text", "type": "boolean" }, "model": { "description": "Optional model id; must be in GET /image/orgs/{org_id}/models. Defaults to GEMINI_IMAGE_MODEL env or gemini-2.5-flash-image.", "type": "string" }, "prompt": { "description": "Natural-language image description", "type": "string" }, "style": { "description": "Optional style hint (e.g. \"flat\", \"photoreal\")", "type": "string" } }, "required": [ "prompt" ], "type": "object" } } }, "description": "Image generation prompt", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "PROMPT_REQUIRED", "UNKNOWN_MODEL", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `PROMPT_REQUIRED` — Send prompt in the body. No job was started.; `UNKNOWN_MODEL` — The model name is not in the catalog. No job was started.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Kick off async image generation (returns job_id). Cost is per-image at the model's catalog rate — see GET /image/orgs/{org_id}/models.", "tags": [ "image" ], "x-safety": { "denylist": false, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/image/orgs/{org_id}/generate/{id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Alias of /image/orgs/{org_id}/jobs/{id} — REST-instinct path for polling a generate job by its job_id.", "tags": [ "image" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/image/orgs/{org_id}/images/{id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Soft-delete an image (keeps job history)", "tags": [ "image" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/image/orgs/{org_id}/jobs/{id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get image-generation job status", "tags": [ "image" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/image/orgs/{org_id}/list": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List images for the org", "tags": [ "image" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/image/orgs/{org_id}/models": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List available image-generation models with per-image pricing. Mirrors the shape of GET /llm/.../models for the image primitive.", "tags": [ "image" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/kms/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of kms: method, path, auth, params, error codes — public, no auth", "tags": [ "kms" ] } }, "/kms/orgs/{org_id}/keys": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List the org's keys with state and primary version. Never material.", "tags": [ "kms" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "What this key protects, 1 to 80 characters.", "type": "string" }, "test": { "description": "Make a test key: free, separate root, disposable.", "type": "boolean" } }, "required": [ "name" ], "type": "object" } } }, "description": "The key", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_JSON", "NAME_REQUIRED", "KEY_LIMIT_REACHED", "INSUFFICIENT_FUNDS", "RATE_LIMITED", "INVALID_REQUEST", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_JSON` — The body is not valid JSON. Nothing was created.; `NAME_REQUIRED` — name is required, 1 to 80 characters. Nothing was created.; `KEY_LIMIT_REACHED` — This org already has the most keys allowed. Nothing was created.; `INSUFFICIENT_FUNDS` — The balance cannot cover the key. Nothing was created.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create an encryption key. Returns the key id; the material never leaves the platform. 5 cents. test:true makes a test key: free, its ciphertexts start with t1, and its material is dropped a day after its last use.", "tags": [ "kms" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low", "test_mode": true } } }, "/kms/orgs/{org_id}/keys/{id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "KEY_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `KEY_NOT_FOUND` — No key with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "One key with its versions and their states. Never material.", "tags": [ "kms" ] } }, "/kms/orgs/{org_id}/keys/{id}/audit": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "The next_cursor from the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "KEY_NOT_FOUND", "CURSOR_INVALID", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `KEY_NOT_FOUND` — No key with that id in this org.; `CURSOR_INVALID` — cursor is not one this list returned; start again without it.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Every operation on the key, newest first, paged: op, version, the api key that called, bytes, whether it succeeded.", "tags": [ "kms" ] } }, "/kms/orgs/{org_id}/keys/{id}/cancel-delete": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "KEY_NOT_FOUND", "NOT_SCHEDULED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `KEY_NOT_FOUND` — No key with that id in this org. Nothing was changed.; `NOT_SCHEDULED` — The key is not scheduled for deletion. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Cancel a scheduled deletion before its date. The key is enabled again.", "tags": [ "kms" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/kms/orgs/{org_id}/keys/{id}/data-keys": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "aad": { "description": "Optional base64 context bound to the wrapped key.", "type": "string" } }, "type": "object" } } }, "description": "Options", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "KEY_NOT_FOUND", "KEY_DISABLED", "KEY_SCHEDULED_FOR_DELETION", "INVALID_JSON", "AAD_INVALID", "CIPHERTEXT_INVALID", "VERSION_DESTROYED", "RATE_LIMITED", "INVALID_REQUEST", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `KEY_NOT_FOUND` — No key with that id in this org. Nothing was processed.; `KEY_DISABLED` — The key is disabled — enable it or use another key. Nothing was processed.; `KEY_SCHEDULED_FOR_DELETION` — The key is scheduled for deletion — cancel the deletion to use it. Nothing was processed.; `INVALID_JSON` — The body is not valid JSON. Nothing was processed.; `AAD_INVALID` — aad must be base64, at most 1 KiB. Nothing was processed.; `CIPHERTEXT_INVALID` — This ciphertext was not made by this key, was altered, or the aad does not match. Nothing was processed.; `VERSION_DESTROYED` — The version that made this ciphertext was destroyed with the key's deletion; the data cannot be read.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Make a data key for bulk data: returns the plaintext key ONCE and its wrapped form. Encrypt your data locally with the plaintext key, store only wrapped_key beside the data, and call unwrap to read again. Billed per thousand operations.", "tags": [ "kms" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/kms/orgs/{org_id}/keys/{id}/decrypt": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "aad": { "description": "The base64 aad used at encrypt, if any.", "type": "string" }, "ciphertext": { "description": "The self-describing ciphertext encrypt returned.", "type": "string" } }, "required": [ "ciphertext" ], "type": "object" } } }, "description": "What to decrypt", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "KEY_NOT_FOUND", "KEY_DISABLED", "KEY_SCHEDULED_FOR_DELETION", "INVALID_JSON", "AAD_INVALID", "CIPHERTEXT_INVALID", "VERSION_DESTROYED", "RATE_LIMITED", "INVALID_REQUEST", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `KEY_NOT_FOUND` — No key with that id in this org. Nothing was processed.; `KEY_DISABLED` — The key is disabled — enable it or use another key. Nothing was processed.; `KEY_SCHEDULED_FOR_DELETION` — The key is scheduled for deletion — cancel the deletion to use it. Nothing was processed.; `INVALID_JSON` — The body is not valid JSON. Nothing was processed.; `AAD_INVALID` — aad must be base64, at most 1 KiB. Nothing was processed.; `CIPHERTEXT_INVALID` — This ciphertext was not made by this key, was altered, or the aad does not match. Nothing was processed.; `VERSION_DESTROYED` — The version that made this ciphertext was destroyed with the key's deletion; the data cannot be read.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Decrypt a ciphertext this key made, with any version that still exists. Send the same aad the encrypt used, if any. Billed per thousand operations.", "tags": [ "kms" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/kms/orgs/{org_id}/keys/{id}/disable": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "KEY_NOT_FOUND", "KEY_STATE_CONFLICT", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `KEY_NOT_FOUND` — No key with that id in this org. Nothing was changed.; `KEY_STATE_CONFLICT` — Only an enabled key can be disabled. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Refuse every operation on the key until it is enabled again. The material is kept.", "tags": [ "kms" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "POST /kms/orgs/{org_id}/keys/{id}/enable", "reversible": true, "risk": "low" } } }, "/kms/orgs/{org_id}/keys/{id}/enable": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "KEY_NOT_FOUND", "KEY_STATE_CONFLICT", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `KEY_NOT_FOUND` — No key with that id in this org. Nothing was changed.; `KEY_STATE_CONFLICT` — Only a disabled key can be enabled; a key scheduled for deletion needs cancel-delete. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Allow operations on a disabled key again.", "tags": [ "kms" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/kms/orgs/{org_id}/keys/{id}/encrypt": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "aad": { "description": "Optional base64 context (up to 1 KiB). Decrypt must send the same aad.", "type": "string" }, "plaintext": { "description": "base64 of the bytes to encrypt, up to 4 KiB. For larger data make a data key.", "type": "string" } }, "required": [ "plaintext" ], "type": "object" } } }, "description": "What to encrypt", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "KEY_NOT_FOUND", "KEY_DISABLED", "KEY_SCHEDULED_FOR_DELETION", "INVALID_JSON", "AAD_INVALID", "CIPHERTEXT_INVALID", "VERSION_DESTROYED", "PLAINTEXT_REQUIRED", "PAYLOAD_TOO_LARGE", "RATE_LIMITED", "INVALID_REQUEST", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `KEY_NOT_FOUND` — No key with that id in this org. Nothing was processed.; `KEY_DISABLED` — The key is disabled — enable it or use another key. Nothing was processed.; `KEY_SCHEDULED_FOR_DELETION` — The key is scheduled for deletion — cancel the deletion to use it. Nothing was processed.; `INVALID_JSON` — The body is not valid JSON. Nothing was processed.; `AAD_INVALID` — aad must be base64, at most 1 KiB. Nothing was processed.; `CIPHERTEXT_INVALID` — This ciphertext was not made by this key, was altered, or the aad does not match. Nothing was processed.; `VERSION_DESTROYED` — The version that made this ciphertext was destroyed with the key's deletion; the data cannot be read.; `PLAINTEXT_REQUIRED` — plaintext is required as base64. Nothing was encrypted.; `PAYLOAD_TOO_LARGE` — Encrypt up to 4 KiB; for larger data make a data key. Nothing was encrypted.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Encrypt up to 4 KiB with the key's current version. Returns a self-describing ciphertext (v1:\u003cversion\u003e:\u003cnonce\u003e:\u003cdata\u003e) that decrypt reads without any other input. Optional aad binds the ciphertext to a context you choose. Billed per thousand operations.", "tags": [ "kms" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/kms/orgs/{org_id}/keys/{id}/re-encrypt": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "aad": { "description": "The base64 aad used at encrypt, if any.", "type": "string" }, "ciphertext": { "description": "A ciphertext this key made, any version.", "type": "string" } }, "required": [ "ciphertext" ], "type": "object" } } }, "description": "The ciphertext", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "KEY_NOT_FOUND", "KEY_DISABLED", "KEY_SCHEDULED_FOR_DELETION", "INVALID_JSON", "AAD_INVALID", "CIPHERTEXT_INVALID", "VERSION_DESTROYED", "RATE_LIMITED", "INVALID_REQUEST", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `KEY_NOT_FOUND` — No key with that id in this org. Nothing was processed.; `KEY_DISABLED` — The key is disabled — enable it or use another key. Nothing was processed.; `KEY_SCHEDULED_FOR_DELETION` — The key is scheduled for deletion — cancel the deletion to use it. Nothing was processed.; `INVALID_JSON` — The body is not valid JSON. Nothing was processed.; `AAD_INVALID` — aad must be base64, at most 1 KiB. Nothing was processed.; `CIPHERTEXT_INVALID` — This ciphertext was not made by this key, was altered, or the aad does not match. Nothing was processed.; `VERSION_DESTROYED` — The version that made this ciphertext was destroyed with the key's deletion; the data cannot be read.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Move a ciphertext to the key's current version: same plaintext, new ciphertext. Use it after a rotation to retire old versions. Billed per thousand operations.", "tags": [ "kms" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/kms/orgs/{org_id}/keys/{id}/rotate": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "KEY_NOT_FOUND", "KEY_DISABLED", "KEY_SCHEDULED_FOR_DELETION", "VERSION_LIMIT_REACHED", "INSUFFICIENT_FUNDS", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `KEY_NOT_FOUND` — No key with that id in this org. Nothing was rotated.; `KEY_DISABLED` — The key is disabled. Nothing was rotated.; `KEY_SCHEDULED_FOR_DELETION` — The key is scheduled for deletion. Nothing was rotated.; `VERSION_LIMIT_REACHED` — The key has the most versions allowed. Create a new key. Nothing was rotated.; `INSUFFICIENT_FUNDS` — The balance cannot cover the rotation. Nothing was rotated.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Make a new primary version. Older versions still decrypt; new encrypts use the new one. 5 cents. re-encrypt moves existing ciphertexts over.", "tags": [ "kms" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/kms/orgs/{org_id}/keys/{id}/schedule-delete": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "KEY_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `KEY_NOT_FOUND` — No key with that id in this org. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete the key in 30 days. Every operation is refused from now; when the date passes the material is destroyed and data encrypted under it cannot be read by anyone. cancel-delete before the date reverses this.", "tags": [ "kms" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reverse": "POST /kms/orgs/{org_id}/keys/{id}/cancel-delete", "reversible": true, "risk": "high" } } }, "/kms/orgs/{org_id}/keys/{id}/unwrap": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "aad": { "description": "The base64 aad used at data-keys, if any.", "type": "string" }, "wrapped_key": { "description": "The wrapped_key data-keys returned.", "type": "string" } }, "required": [ "wrapped_key" ], "type": "object" } } }, "description": "The wrapped key", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "KEY_NOT_FOUND", "KEY_DISABLED", "KEY_SCHEDULED_FOR_DELETION", "INVALID_JSON", "AAD_INVALID", "CIPHERTEXT_INVALID", "VERSION_DESTROYED", "RATE_LIMITED", "INVALID_REQUEST", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `KEY_NOT_FOUND` — No key with that id in this org. Nothing was processed.; `KEY_DISABLED` — The key is disabled — enable it or use another key. Nothing was processed.; `KEY_SCHEDULED_FOR_DELETION` — The key is scheduled for deletion — cancel the deletion to use it. Nothing was processed.; `INVALID_JSON` — The body is not valid JSON. Nothing was processed.; `AAD_INVALID` — aad must be base64, at most 1 KiB. Nothing was processed.; `CIPHERTEXT_INVALID` — This ciphertext was not made by this key, was altered, or the aad does not match. Nothing was processed.; `VERSION_DESTROYED` — The version that made this ciphertext was destroyed with the key's deletion; the data cannot be read.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Unwrap a data key made by data-keys and return its plaintext. Billed per thousand operations.", "tags": [ "kms" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/launch/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of launch: method, path, auth, params, error codes — public, no auth", "tags": [ "launch" ] } }, "/launch/orgs/{org_id}/jobs": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List launch jobs for the org, newest first.", "tags": [ "launch" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "auth_tenant": { "description": "Provision the org's auth tenant (default false).", "type": "boolean" }, "domain": { "description": "Domain to serve on. A domain already in this org is used as-is; a new one is registered and charged at the price shown by GET /domain/orgs/{org_id}/check/available/{domain}.", "type": "string" }, "mailbox": { "description": "Local part of the first mailbox (default \"hello\"). Sending is activated in the same step.", "type": "string" }, "page_html": { "description": "HTML to publish at /. Omitted: a placeholder page is built from the org's branding fields.", "type": "string" }, "registrant": { "description": "WHOIS contact for a new registration — same shape as POST /domain/orgs/{org_id}/register. Ignored for an existing domain.", "properties": {}, "type": "object" } }, "required": [ "domain" ], "type": "object" } } }, "description": "Launch payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "LAUNCH_INSUFFICIENT_BALANCE", "INVALID_DOMAIN", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `LAUNCH_INSUFFICIENT_BALANCE` — The balance cannot cover the launch estimate. The launch was NOT started and nothing was charged. Add funds: POST /hq/billing/topup.; `INVALID_DOMAIN` — The domain is not a valid name like acme.com. The launch was NOT started.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Start a launch: domain + published page + email + optional auth, wired together. Returns job_id — poll GET /launch/orgs/{org_id}/jobs/{id}. Money is spent per step as steps complete; a refusal before the first step spends nothing. Send the standard Idempotency-Key header to make retries safe.", "tags": [ "launch" ], "x-safety": { "denylist": true, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/launch/orgs/{org_id}/jobs/{id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Launch job status: overall state plus every step with its own status, result and error code. Error codes are the same ones the underlying primitives return; a skipped step names why in result.reason.", "tags": [ "launch" ] } }, "/launch/orgs/{org_id}/jobs/{id}/resume": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "LAUNCH_STEP_BLOCKED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `LAUNCH_STEP_BLOCKED` — The failed step's cause is not fixed yet, or the job is already running. The message names the step and the fix; the resume did NOT start.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Re-run a launch from its first incomplete step, after fixing the cause of a failure. Completed steps are not repeated and not re-charged.", "tags": [ "launch" ], "x-safety": { "denylist": false, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/launch/orgs/{org_id}/online": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "audience": { "description": "Who it is for, in a few words — shown under the pitch. Optional.", "type": "string" }, "name": { "description": "What the product is called, 1 to 80 characters. Becomes the headline, the page title and the org's name when the org is still unnamed.", "type": "string" }, "pitch": { "description": "One sentence on what it is and who it is for, 600 characters or fewer.", "type": "string" }, "waitlist": { "description": "Say on the page that a waitlist is coming. It does NOT create one: offer pages record who joins (POST /offer/orgs/{org_id}/offers).", "type": "boolean" } }, "required": [ "name", "pitch" ], "type": "object" } } }, "description": "What to put online", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NAME_REQUIRED", "NAME_INVALID", "PITCH_REQUIRED", "PITCH_TOO_LONG", "AUDIENCE_TOO_LONG", "PUBLISH_FAILED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NAME_REQUIRED` — name was empty. Nothing was published.; `NAME_INVALID` — name must be 1 to 80 characters on one line. Nothing was published.; `PITCH_REQUIRED` — pitch was empty. Nothing was published.; `PITCH_TOO_LONG` — pitch must be 600 characters or fewer. Nothing was published.; `AUDIENCE_TOO_LONG` — audience must be 200 characters or fewer. Nothing was published.; `PUBLISH_FAILED` — The page could not be published. Nothing was changed; retry.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Put a product online in one call: publish its first page and return the URL it answers on. Give the name and one sentence about it; the org's site is created if it does not exist yet, and an org nobody has named is named after the product. Calling it again with the same org rewrites that page instead of making a second site — the previous version is kept and can be restored. The page says plainly that nothing is wired to it yet, so it never claims a signup it cannot record.", "tags": [ "launch" ], "x-safety": { "denylist": false, "disclosure": "live_site_change", "kind": "mutate", "proof": [ "http" ], "reverse": "POST /funnel/orgs/{org_id}/funnels/{id}/versions/{version_id}/restore", "reversible": true, "risk": "high" } } }, "/llm/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of llm: method, path, auth, params, error codes — public, no auth", "tags": [ "llm" ] } }, "/llm/orgs/{org_id}/caches": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List the org's live context caches with their size and expiry. A cache that has expired is not listed — the provider removes it on its own and it stops being chargeable.", "tags": [ "llm" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "content": { "description": "The prefix to store — a system prompt, a reference document, anything you would otherwise resend every call.", "type": "string" }, "model": { "description": "A model from GET /llm/orgs/{org_id}/models. The cache cannot be used with any other.", "type": "string" }, "ttl_seconds": { "description": "How long to keep it. Default 3600, maximum 86400; a longer request is shortened rather than refused.", "type": "integer" } }, "required": [ "model", "content" ], "type": "object" } } }, "description": "Cache", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "CACHE_NOT_FOUND", "CACHE_MODEL_MISMATCH", "MODEL_REQUIRED", "CONTENT_REQUIRED", "CACHE_NOT_CREATED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `CACHE_NOT_FOUND` — No live cache with that id in this org. A cache expires on its own.; `CACHE_MODEL_MISMATCH` — That cache was built for a different model and cannot be used with this one.; `MODEL_REQUIRED` — model must be one from GET /llm/orgs/{org_id}/models.; `CONTENT_REQUIRED` — content is the prefix to store and cannot be empty.; `CACHE_NOT_CREATED` — The provider did not store it. Nothing was created and nothing was charged.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Store a long prompt prefix with the model provider and get an id for it. Reading a cached prefix costs a TENTH of reading it fresh, so a system prompt or reference document you send with every call is worth storing once. Send `cache_id` on POST /llm/orgs/{org_id}/complete to use it. A cache is bound to ONE model and expires on its own; `ttl_seconds` defaults to 3600 and is capped at 86400. IT COSTS MONEY WHILE IT EXISTS, read or not, so delete it when you are done rather than waiting for the expiry.", "tags": [ "llm" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /llm/orgs/{org_id}/caches/{id}", "reversible": true, "risk": "low" } } }, "/llm/orgs/{org_id}/caches/{id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "CACHE_NOT_DELETED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `CACHE_NOT_DELETED` — The provider still holds it and it is still being charged. Try again.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete a context cache now, which is the only way to stop its storage charge before the TTL runs out. Idempotent: an unknown id answers the same way, so an id cannot be probed across orgs.", "tags": [ "llm" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/llm/orgs/{org_id}/chat/completions": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "max_tokens": { "description": "Cap on generated tokens", "type": "integer" }, "messages": { "description": "Conversation so far", "items": { "description": "A chat message", "properties": { "content": { "description": "Message text", "type": "string" }, "role": { "description": "Author of the message", "enum": [ "system", "user", "assistant", "tool" ], "type": "string" } }, "type": "object" }, "type": "array" }, "model": { "description": "Model id or alias (myapi-fast / myapi-balanced / myapi-pro)", "type": "string" }, "response_format": { "additionalProperties": true, "description": "Force JSON output (json_object or json_schema). Every tier takes the same JSON Schema: keywords the model cannot take (additionalProperties, const, oneOf, exclusive bounds, formats other than date/time) are removed before sending and checked on the answer instead; an answer that misses the schema is refused with 422.", "type": "object" }, "stop": { "description": "Stop sequences", "items": { "description": "A sequence that ends generation", "type": "string" }, "type": "array" }, "stream": { "description": "Stream the response as server-sent events", "type": "boolean" }, "temperature": { "description": "Sampling temperature", "type": "number" }, "tool_choice": { "additionalProperties": true, "description": "Constrain which tool the model may call", "type": "object" }, "tools": { "description": "Tool definitions for function calling", "items": { "additionalProperties": true, "description": "A tool definition", "type": "object" }, "type": "array" } }, "required": [ "model", "messages" ], "type": "object" } } }, "description": "OpenAI-shaped chat completion request", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "OpenAI-compatible chat-completion endpoint. Same model catalog as /complete, OpenAI response shape (NOT the standard envelope). Drop-in for the OpenAI SDK — point base_url at /llm/orgs/{org_id}.", "tags": [ "llm" ], "x-safety": { "denylist": false, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/llm/orgs/{org_id}/complete": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "cache_id": { "description": "Id from POST /llm/orgs/{org_id}/caches. Re-reads that stored prefix at a tenth the input price; the cache must have been built for the same model. The reply's usage.cached_input_tokens is the part of input_tokens served from it — a subset, not an addition.", "type": "string" }, "max_tokens": { "description": "Max output tokens (optional; per-model default applies).", "type": "integer" }, "messages": { "description": "Conversation turns. Each item is { role: 'system'|'user'|'assistant', content: '...' }. system messages collapse to a single system instruction.", "items": { "description": "Message", "properties": { "content": { "description": "Message text", "type": "string" }, "role": { "description": "Role", "enum": [ "system", "user", "assistant" ], "type": "string" } }, "type": "object" }, "type": "array" }, "model": { "description": "Model id; must be in the catalog (kind='chat'). Call GET /llm/.../models for the ids currently available.", "type": "string" }, "stop": { "description": "Optional stop sequences.", "items": { "description": "stop string", "type": "string" }, "type": "array" }, "temperature": { "description": "Sampling temperature 0–1 (optional).", "type": "integer" } }, "required": [ "model", "messages" ], "type": "object" } } }, "description": "Chat-completion request", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "CACHE_NOT_FOUND", "CACHE_MODEL_MISMATCH", "MESSAGES_REQUIRED", "MODEL_NOT_IN_RAW_CATALOG", "RESPONSE_FORMAT_INVALID", "RESPONSE_FORMAT_UNSUPPORTED", "SCHEMA_NOT_MET", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `CACHE_NOT_FOUND` — No live cache with that id in this org. A cache expires on its own.; `CACHE_MODEL_MISMATCH` — That cache was built for a different model and cannot be used with this one.; `MESSAGES_REQUIRED` — Send at least one message in messages.; `MODEL_NOT_IN_RAW_CATALOG` — The model is not in the raw catalog. List models: GET /llm/models; `RESPONSE_FORMAT_INVALID` — response_format is malformed: type must be json_object or json_schema, and json_schema.schema must be a JSON object.; `RESPONSE_FORMAT_UNSUPPORTED` — The model tier could not take this json_schema. Keep to types, properties, required, enum, items and min/max items; nothing was generated or charged.; `SCHEMA_NOT_MET` — The model answered but the answer does not match json_schema at the path named. The answer is withheld; send again or loosen the schema.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Chat completion. Pass messages array (role/content) and a model id from GET /llm/.../models. Returns the assistant reply + usage (tokens + cost_usd at upstream rates).", "tags": [ "llm" ], "x-safety": { "denylist": false, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/llm/orgs/{org_id}/embed": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "input": { "description": "Text to embed; may also be passed as a JSON array of strings for batch.", "type": "string" }, "model": { "description": "Model id; must be in the catalog (kind='embed'). Call GET /llm/.../models for the ids currently available.", "type": "string" } }, "required": [ "model", "input" ], "type": "object" } } }, "description": "Embedding request", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MODEL_NOT_IN_RAW_CATALOG", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MODEL_NOT_IN_RAW_CATALOG` — The model is not in the raw catalog. List models: GET /llm/models; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Embeddings. Pass an embedding model id and input (string or array of strings); returns one vector per input + usage.", "tags": [ "llm" ], "x-safety": { "denylist": false, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/llm/orgs/{org_id}/models": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List available self-hosted LLM models with per-1M-token pricing in cents. The cost_cents in /complete responses is computed from these rates.", "tags": [ "llm" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/llm/orgs/{org_id}/tasks/{verb}": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "verb", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "input": { "description": "The text the task operates on (for draft, may be empty when context/prompt carry the brief).", "type": "string" }, "kind": { "description": "draft: what to write (email, message, …).", "type": "string" }, "labels": { "description": "classify: candidate labels.", "items": { "description": "label", "type": "string" }, "type": "array" }, "multi": { "description": "classify: allow multiple labels.", "type": "boolean" }, "prompt": { "description": "draft: free-text instructions.", "type": "string" }, "schema": { "additionalProperties": true, "description": "extract: JSON Schema the extracted object must conform to.", "type": "object" }, "style": { "description": "summarize: brief | exec | bullet.", "enum": [ "brief", "exec", "bullet" ], "type": "string" }, "tier": { "description": "Which model to run, by its public name: myapi-fast | myapi-balanced (default) | myapi-pro. `cheap` is a legacy name for myapi-fast, `fast` (the default) for myapi-balanced, `reasoning` for myapi-pro; the bare `balanced` and `pro` mean myapi-balanced and myapi-pro. Any other value is refused, never quietly downgraded. The answer's usage.model names the alias that ran and was billed.", "enum": [ "myapi-fast", "myapi-balanced", "myapi-pro", "cheap", "fast", "reasoning", "balanced", "pro" ], "type": "string" } }, "required": [ "input" ], "type": "object" } } }, "description": "Objective task request", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "UNKNOWN_VERB", "INPUT_REQUIRED", "INVALID_INPUT", "INVALID_JSON", "TIER_UNKNOWN", "LLM_UNAVAILABLE", "LLM_PROVIDER_ERROR", "RATE_LIMITED", "INVALID_REQUEST", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `UNKNOWN_VERB` — The verb is not one of classify, extract, summarize, draft.; `INPUT_REQUIRED` — The request has no input to work on.; `INVALID_INPUT` — The input could not be used for this verb — see the message.; `INVALID_JSON` — The request body is not valid JSON.; `TIER_UNKNOWN` — The tier is not one we serve. Nothing was generated and nothing was charged.; `LLM_UNAVAILABLE` — The model service is not reachable right now. Retry.; `LLM_PROVIDER_ERROR` — The model service returned an error. The request was NOT billed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Objective-based completion. {verb} ∈ classify | extract | summarize | draft. Body is { input, tier? } plus verb-specific fields (classify: labels[], multi?; extract: schema; summarize: style?; draft: kind, context?, prompt?). Returns { data, usage }; usage.model names the public model alias that ran and was billed (usage.tier_used is the legacy internal word for the same choice).", "tags": [ "llm" ], "x-safety": { "denylist": false, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/llm/orgs/{org_id}/v1/chat/completions": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "max_tokens": { "description": "Cap on generated tokens", "type": "integer" }, "messages": { "description": "Conversation so far", "items": { "description": "A chat message", "properties": { "content": { "description": "Message text", "type": "string" }, "role": { "description": "Author of the message", "enum": [ "system", "user", "assistant", "tool" ], "type": "string" } }, "type": "object" }, "type": "array" }, "model": { "description": "Model id or alias (myapi-fast / myapi-balanced / myapi-pro)", "type": "string" }, "response_format": { "additionalProperties": true, "description": "Force JSON output (json_object or json_schema). Every tier takes the same JSON Schema: keywords the model cannot take (additionalProperties, const, oneOf, exclusive bounds, formats other than date/time) are removed before sending and checked on the answer instead; an answer that misses the schema is refused with 422.", "type": "object" }, "stop": { "description": "Stop sequences", "items": { "description": "A sequence that ends generation", "type": "string" }, "type": "array" }, "stream": { "description": "Stream the response as server-sent events", "type": "boolean" }, "temperature": { "description": "Sampling temperature", "type": "number" }, "tool_choice": { "additionalProperties": true, "description": "Constrain which tool the model may call", "type": "object" }, "tools": { "description": "Tool definitions for function calling", "items": { "additionalProperties": true, "description": "A tool definition", "type": "object" }, "type": "array" } }, "required": [ "model", "messages" ], "type": "object" } } }, "description": "OpenAI-shaped chat completion request", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Alias of /llm/orgs/{org_id}/chat/completions for SDKs that hard-code /v1.", "tags": [ "llm" ], "x-safety": { "denylist": false, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/mcp": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "Request id (number or string). Omit it to send a notification.", "type": "string" }, "jsonrpc": { "description": "Always \"2.0\".", "type": "string" }, "method": { "description": "initialize | ping | tools/list | tools/call", "type": "string" }, "params": { "description": "Method parameters. For tools/call: {name, arguments}.", "properties": {}, "type": "object" } }, "required": [ "jsonrpc", "method" ], "type": "object" } } }, "description": "One JSON-RPC 2.0 message", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MCP_VERSION_UNSUPPORTED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MCP_VERSION_UNSUPPORTED` — The MCP-Protocol-Version header names a revision this server does not speak. The message was NOT processed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "MCP endpoint for the connection (JSON-RPC 2.0 over Streamable HTTP). Methods: initialize, ping, tools/list, tools/call. Send your API key as Authorization: Bearer. No org in the path: every tool takes org_id and it selects the target org. A key locked to one org may act only on that org; an account-scoped key may act on any org the account owns. Responses are a single JSON body by default; an Accept header that includes text/event-stream gets an SSE stream with progress notifications.", "tags": [ "mcp" ] } }, "/mcp/for/{profile}": { "post": { "parameters": [ { "in": "path", "name": "profile", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "Request id (number or string). Omit it to send a notification.", "type": "string" }, "jsonrpc": { "description": "Always \"2.0\".", "type": "string" }, "method": { "description": "initialize | ping | tools/list | tools/call", "type": "string" }, "params": { "description": "Method parameters. For tools/call: {name, arguments}.", "properties": {}, "type": "object" } }, "required": [ "jsonrpc", "method" ], "type": "object" } } }, "description": "One JSON-RPC 2.0 message", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MCP_VERSION_UNSUPPORTED", "MCP_LISTING_UNKNOWN", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MCP_VERSION_UNSUPPORTED` — The MCP-Protocol-Version header names a revision this server does not speak. The message was NOT processed.; `MCP_LISTING_UNKNOWN` — The path names no listing. Use /mcp/for/anthropic, /mcp/for/openai, or /mcp for the full tool set.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "MCP endpoint for one connector-directory listing. Same JSON-RPC surface and sign-in as POST /mcp; the tool set is the one that listing offers (anthropic, openai). A tool outside the listing is refused by name with the endpoint that offers it. Every tool call's org_id selects the target org.", "tags": [ "mcp" ] } }, "/mcp/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of mcp: method, path, auth, params, error codes — public, no auth", "tags": [ "mcp" ] } }, "/mcp/o/{org_id}": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "Request id (number or string). Omit it to send a notification.", "type": "string" }, "jsonrpc": { "description": "Always \"2.0\".", "type": "string" }, "method": { "description": "initialize | ping | tools/list | tools/call", "type": "string" }, "params": { "description": "Method parameters. For tools/call: {name, arguments}.", "properties": {}, "type": "object" } }, "required": [ "jsonrpc", "method" ], "type": "object" } } }, "description": "One JSON-RPC 2.0 message", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MCP_VERSION_UNSUPPORTED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MCP_VERSION_UNSUPPORTED` — The MCP-Protocol-Version header names a revision this server does not speak. The message was NOT processed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "MCP endpoint for one org (JSON-RPC 2.0 over Streamable HTTP). Methods: initialize, ping, tools/list, tools/call. Send your API key as Authorization: Bearer. Every tool takes org_id and it must match the org in the path. Responses are a single JSON body by default; an Accept header that includes text/event-stream gets the response as an SSE stream, with progress notifications when the call carries a progressToken.", "tags": [ "mcp" ] } }, "/mcp/oauth/authorize": { "get": { "parameters": [ { "description": "Your client_id from POST /mcp/oauth/register.", "in": "query", "name": "client_id", "required": true, "schema": { "type": "string" } }, { "description": "One of the redirect_uris you registered.", "in": "query", "name": "redirect_uri", "required": true, "schema": { "type": "string" } }, { "description": "Always \"code\".", "in": "query", "name": "response_type", "required": true, "schema": { "type": "string" } }, { "description": "PKCE challenge: base64url(sha256(code_verifier)), no padding.", "in": "query", "name": "code_challenge", "required": true, "schema": { "type": "string" } }, { "description": "Always \"S256\".", "in": "query", "name": "code_challenge_method", "required": true, "schema": { "type": "string" } }, { "description": "Opaque value echoed back on the redirect. Use it to tie the redirect to your request.", "in": "query", "name": "state", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "OAuth authorization endpoint. Sends the person through sign-in and a one-button consent page, then back to redirect_uri with a single-use code. Connecting means the app acts as the person: every organization in the account, now and later, up to the default monthly cap. The person narrows or revokes it later at GET /hq/connections.", "tags": [ "mcp" ] } }, "/mcp/oauth/callback": { "get": { "parameters": [ { "description": "Authorization code from the hosted login. Set by the sign-in redirect.", "in": "query", "name": "code", "required": true, "schema": { "type": "string" } }, { "description": "Connect-flow request id. Set by the sign-in redirect.", "in": "query", "name": "state", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Sign-in return leg of the connect flow. Browsers arrive here from the hosted login; do not call it directly.", "tags": [ "mcp" ] } }, "/mcp/oauth/consent": { "post": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Consent form submit of the connect flow. The consent page posts here; do not call it directly.", "tags": [ "mcp" ] } }, "/mcp/oauth/register": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "client_name": { "description": "Display name shown on the consent page listing.", "type": "string" }, "redirect_uris": { "description": "The client's redirect URIs (JSON array of strings): https URLs, or http loopback for a native client.", "type": "string" } }, "required": [ "redirect_uris" ], "type": "object" } } }, "description": "Client metadata", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Register an MCP client (RFC 7591). Send redirect_uris (https, or http loopback for a native client) and an optional client_name; the response carries your client_id. Every client is public — PKCE, no secret.", "tags": [ "mcp" ] } }, "/mcp/oauth/token": { "post": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "OAuth token endpoint. grant_type=authorization_code exchanges the code (code, code_verifier, client_id, redirect_uri) for an access token plus a refresh_token. The access token is an API key that acts on the whole account, unless the person later limits it at GET /hq/connections; send it as Authorization: Bearer on the mcp_url in the response. grant_type=refresh_token (refresh_token, client_id) rotates the key's secret and returns a new access token and a new single-use refresh token; delete the key to revoke the whole chain.", "tags": [ "mcp" ] } }, "/mcp/operator": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "Request id (number or string). Omit it to send a notification.", "type": "string" }, "jsonrpc": { "description": "Always \"2.0\".", "type": "string" }, "method": { "description": "initialize | ping | tools/list | tools/call", "type": "string" }, "params": { "description": "Method parameters. For tools/call: {name, arguments}.", "properties": {}, "type": "object" } }, "required": [ "jsonrpc", "method" ], "type": "object" } } }, "description": "One JSON-RPC 2.0 message", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MCP_VERSION_UNSUPPORTED", "OPERATOR_REQUIRED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MCP_VERSION_UNSUPPORTED` — The MCP-Protocol-Version header names a revision this server does not speak. The message was NOT processed.; `OPERATOR_REQUIRED` — The key is locked to one org. This endpoint needs a connection that acts on the whole account. Widen it at GET /hq/connections.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "MCP endpoint for the whole account. Same JSON-RPC surface as /mcp/o/{org_id}, plus create_org and account-wide org_list. Needs a key that acts on the whole account — what the connect flow mints; a key locked to one org is refused. Every tool call's org_id selects the target org and must belong to the account.", "tags": [ "mcp" ] } }, "/mcp/orgs/{org_id}/hostname": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete the org's custom MCP hostname. The edge routing and DNS record go with it, and the endpoint is reachable at the platform address again.", "tags": [ "mcp" ] }, "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Read the org's MCP endpoint address. Returns the custom hostname when one is bound, and the endpoint URL to give an MCP client either way.", "tags": [ "mcp" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "hostname": { "description": "The hostname to bind, for example mcp.your-brand.com. Must be inside a domain the org registered through MyAPI.", "type": "string" } }, "required": [ "hostname" ], "type": "object" } } }, "description": "Custom hostname payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "ORG_HOSTNAME_TAKEN", "HOSTNAME_TAKEN", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `ORG_HOSTNAME_TAKEN` — The org already has a custom hostname. Delete it first. Nothing was changed.; `HOSTNAME_TAKEN` — The hostname is already bound to another org. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Bind a hostname of your own to the org's MCP endpoint, so an agent connects to mcp.your-brand.com instead of the platform address. The hostname must sit inside a domain the org registered through MyAPI: it is put on the edge inside that domain's zone, so it is served over TLS within minutes and needs no certificate of yours. The hostname serves the MCP endpoint and its OAuth discovery documents only; every other path answers 404. One hostname per org.", "tags": [ "mcp" ] } }, "/offer/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of offer: method, path, auth, params, error codes — public, no auth", "tags": [ "offer" ] } }, "/offer/offers/{id}/act": { "post": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "The attribution tag, when the form's URL carries ?src= instead of a src field.", "in": "query", "name": "src", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "action": { "description": "Which button: join (waitlist), buy (fake door), reserve (pre-order). Default: the offer's own.", "enum": [ "join", "buy", "reserve" ], "type": "string" }, "email": { "description": "The visitor's email. Required for join and reserve.", "type": "string" }, "src": { "description": "The attribution tag the visitor arrived with.", "type": "string" }, "website": { "description": "Honeypot. Leave empty.", "type": "string" } }, "type": "object" } } }, "description": "The visitor's action (form-encoded from the page, or JSON)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "OFFER_NOT_FOUND", "OFFER_NOT_LIVE", "INVALID_BODY", "EMAIL_REQUIRED", "ACTION_INVALID", "RATE_LIMITED", "PAYMENTS_NOT_CONNECTED", "CHECKOUT_FAILED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `OFFER_NOT_FOUND` — No offer with that id.; `OFFER_NOT_LIVE` — The offer is unpublished. Nothing was recorded.; `INVALID_BODY` — The form could not be read. Nothing was recorded.; `EMAIL_REQUIRED` — Send a valid email. Nothing was recorded.; `ACTION_INVALID` — That action does not fit this offer's kind. Nothing was recorded.; `RATE_LIMITED` — Too many tries from this address. Wait a minute.; `PAYMENTS_NOT_CONNECTED` — This offer cannot take payments right now. Nothing was charged.; `CHECKOUT_FAILED` — The payment page could not be opened. Nothing was charged." } }, "summary": "Public: what the offer page's form posts. Records the visitor's action (join the list, click buy, reserve) and answers with a page — or JSON when Accept is application/json. Rate-limited per address.", "tags": [ "offer" ] } }, "/offer/orgs/{org_id}/offers": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Rows per page (1..500, default 50).", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List the org's offers, newest first.", "tags": [ "offer" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "button_text": { "description": "The button's words. Default depends on kind.", "type": "string" }, "currency": { "description": "ISO currency, default usd.", "type": "string" }, "deposit_cents": { "description": "preorder: the deposit charged at checkout.", "type": "integer" }, "funnel_id": { "description": "Which funnel to publish on. Default: the org's newest.", "type": "string" }, "headline": { "description": "The offer in one line. The page's title.", "type": "string" }, "kind": { "description": "What acting means", "enum": [ "waitlist", "fake_door", "preorder" ], "type": "string" }, "price_cents": { "description": "fake_door: the price shown on the button.", "type": "integer" }, "promise": { "description": "One short paragraph under the headline.", "type": "string" }, "refund_text": { "description": "preorder: the refund rule, shown on the page. Required for preorder.", "type": "string" }, "slug": { "description": "Page path on the funnel, default /. Ignored when test is true.", "type": "string" }, "test": { "description": "Publish at an unlisted slug; every signup and event is flagged test and never counts.", "type": "boolean" } }, "required": [ "kind", "headline" ], "type": "object" } } }, "description": "The offer", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "KIND_INVALID", "HEADLINE_REQUIRED", "PRICE_REQUIRED", "DEPOSIT_REQUIRED", "REFUND_TEXT_REQUIRED", "PAYMENTS_NOT_CONNECTED", "NO_FUNNEL", "INVALID_SLUG", "PUBLISH_FAILED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `KIND_INVALID` — kind must be waitlist, fake_door or preorder. Nothing was published.; `HEADLINE_REQUIRED` — Send headline. Nothing was published.; `PRICE_REQUIRED` — A fake door shows a price: send price_cents \u003e 0. Nothing was published.; `DEPOSIT_REQUIRED` — A pre-order takes a deposit: send deposit_cents \u003e 0. Nothing was published.; `REFUND_TEXT_REQUIRED` — A pre-order page must state the refund rule: send refund_text. Nothing was published.; `PAYMENTS_NOT_CONNECTED` — A pre-order needs a connected payment account. Connect one first. Nothing was published.; `NO_FUNNEL` — This org has no funnel to publish on. Create one first. Nothing was published.; `INVALID_SLUG` — The slug is not a usable page path — see the message. Nothing was published.; `PUBLISH_FAILED` — The page could not be published. Nothing was published; retry.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Publish an offer page and count who acts on it. kind decides what \"act\" means: waitlist — join a list; fake_door — click buy and be told the truth (not ready yet, nothing charged, join the list); preorder — pay a real deposit through your connected payment account, so the page must state the refund rule. The page goes live on your funnel at slug (default /). test:true publishes at an unlisted slug and flags every signup and event as test, so they never count. A pre-order takes money from visitors: say so when you agree to it.", "tags": [ "offer" ], "x-safety": { "denylist": false, "disclosure": "live_site_change", "kind": "mutate", "proof": [ "http" ], "reverse": "POST /offer/orgs/{org_id}/offers/{id}/unpublish", "reversible": true, "risk": "high" } } }, "/offer/orgs/{org_id}/offers/{id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "OFFER_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `OFFER_NOT_FOUND` — No offer with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Read one offer with what it taught: visits and humans (from the platform beacon on the page), acted (signups, test rows excluded), acted_rate (acted over humans), and the split by src — the tag an attributed link carries.", "tags": [ "offer" ] } }, "/offer/orgs/{org_id}/offers/{id}/signups": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Rows per page (1..500, default 50).", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "OFFER_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `OFFER_NOT_FOUND` — No offer with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Who acted, newest first: kind (waitlisted, clicked_buy, preordered), email, src, test. A list outreach can use later.", "tags": [ "offer" ] } }, "/offer/orgs/{org_id}/offers/{id}/unpublish": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "OFFER_NOT_FOUND", "PUBLISH_FAILED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `OFFER_NOT_FOUND` — No offer with that id in this org.; `PUBLISH_FAILED` — The page could not be taken down. The offer is still live; retry.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Take the page down — the reverse of creating the offer. The list of who acted stays.", "tags": [ "offer" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/ops/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of ops: method, path, auth, params, error codes — public, no auth", "tags": [ "ops" ] } }, "/ops/status": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Diagnostic — database connectivity, key-value store config, email sending state, build info, and whether the usage reconcilers are current.", "tags": [ "ops" ] } }, "/outcome/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of outcome: method, path, auth, params, error codes — public, no auth", "tags": [ "outcome" ] } }, "/outcome/orgs/{org_id}/experiments": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List this org's experiments, newest first, each with its brief: what it cost, who acted, what each person who acted cost, and how close it is to stopping. Every number comes from a record — a spend from the charges attributed to the run, a count from the events themselves — and reads zero when nothing has happened.", "tags": [ "outcome" ] } }, "/outcome/orgs/{org_id}/experiments/{id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "EXPERIMENT_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `EXPERIMENT_NOT_FOUND` — No experiment with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Read one experiment and its brief: the hypothesis, what it teaches, the stop rule in words, what has been spent, who acted and of which kind, cost per person who acted, and the verdict once it has stopped.", "tags": [ "outcome" ] } }, "/outcome/orgs/{org_id}/experiments/{id}/stop": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "EXPERIMENT_NOT_FOUND", "ALREADY_STOPPED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `EXPERIMENT_NOT_FOUND` — No experiment with that id in this org.; `ALREADY_STOPPED` — This experiment already stopped — read it with GET to see its verdict. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Stop an experiment now, before its rule fires. What ran stays; the verdict records that you stopped it and what it had cost. The platform stops an experiment on its own only when the rule you wrote fires — it never starts work and never spends on its own.", "tags": [ "outcome" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/outcome/orgs/{org_id}/outcomes": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List outcomes, newest first.", "tags": [ "outcome" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "budget_cents": { "description": "Optional spend cap for the run, in cents. Every charge made while a step runs is attributed to the outcome; a step that would start past the cap is not started (OUTCOME_BUDGET_EXCEEDED, needs_attention). Omit for no cap — the org and account caps still apply.", "type": "integer" }, "request": { "description": "What you want, in plain words (8..4000 chars). Example: \"visitors can pay on my landing page\".", "type": "string" } }, "required": [ "request" ], "type": "object" } } }, "description": "The request", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "REQUEST_REQUIRED", "INVALID_BUDGET", "PLANNER_NOT_READY", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `REQUEST_REQUIRED` — Send request: what you want, in plain words. Nothing was planned or charged.; `INVALID_BUDGET` — budget_cents must be a positive number of cents. Nothing was planned or charged.; `PLANNER_NOT_READY` — The planner is starting. Try again in a moment; nothing was charged.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Say what you want in plain words; get back a spec: 1-6 claims about what will be true, each with how it will be proven, plus disclosures and undo notes — or 1-3 questions when the request is ambiguous. Nothing executes: you agree to the spec first (POST .../agree). Planning is metered at catalog LLM rates and charged per call.", "tags": [ "outcome" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/outcome/orgs/{org_id}/outcomes/stats": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "The gate numbers for this org: outcomes planned, agreed, agreed UNEDITED (no change replan), that asked questions, that failed to plan, done — and the agreeable-unedited rate. Undo outcomes are excluded.", "tags": [ "outcome" ] } }, "/outcome/orgs/{org_id}/outcomes/{id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "OUTCOME_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `OUTCOME_NOT_FOUND` — No outcome with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Read one outcome: request, status, spec (claims, disclosures, undo notes), plan, questions, and turns — the conversation so far, oldest first: what you said and what Sabaki answered, with the spec or questions each answer showed.", "tags": [ "outcome" ] } }, "/outcome/orgs/{org_id}/outcomes/{id}/agree": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_AGREEABLE", "PLAN_STALE", "OUTCOME_BUDGET_TOO_LOW", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_AGREEABLE` — Only an outcome with a ready spec can be agreed. Read it with GET; answer its questions first if it asked any.; `PLAN_STALE` — The plan is out of date. Nothing was run — say what to change and it is replanned.; `OUTCOME_BUDGET_TOO_LOW` — The plan's priced steps already cost more than budget_cents. Nothing was started and nothing more was charged — raise the budget with POST .../budget, or replan with fewer paid steps.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Agree to the spec and start the work. If the outcome carries budget_cents, the plan's priced steps are totalled first and a plan that cannot fit is refused before anything runs — the budget used to be checked only BETWEEN steps, so a single step costing more than the whole budget spent it in full and only then stopped. The total is a FLOOR: steps priced per unit (model tokens, container time) cannot be costed from the plan alone. Agreement approves every disclosed step; the plan runs step by step, then every claim's verifier runs. Done means proven: status done requires each claim verified (or waiting on a real event, for watch claims). A failed step parks the outcome at needs_attention; a failed claim lands it at partly_done — keep it, or fix the cause and POST .../resume to re-run and re-verify. Completed steps are never repeated.", "tags": [ "outcome" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/outcome/orgs/{org_id}/outcomes/{id}/answer": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "answers": { "additionalProperties": true, "description": "{question_id: answer} for each question the outcome asked.", "type": "object" } }, "required": [ "answers" ], "type": "object" } } }, "description": "The answers", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "ANSWERS_REQUIRED", "OUTCOME_NOT_FOUND", "WRONG_STATUS", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `ANSWERS_REQUIRED` — Send answers: {question_id: answer}. Nothing was replanned or charged.; `OUTCOME_NOT_FOUND` — No outcome with that id in this org.; `WRONG_STATUS` — This outcome has no open questions. Read it with GET.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Answer the planner's questions; the outcome replans with your answers (charged like a plan).", "tags": [ "outcome" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/outcome/orgs/{org_id}/outcomes/{id}/budget": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "budget_cents": { "description": "Cents. 0 removes the cap.", "type": "integer" } }, "required": [ "budget_cents" ], "type": "object" } } }, "description": "The cap", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_BUDGET", "OUTCOME_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_BUDGET` — Send budget_cents: a number of cents (0 removes the cap).; `OUTCOME_NOT_FOUND` — No outcome with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Set or raise the outcome's spend cap. Use it after OUTCOME_BUDGET_EXCEEDED, then POST .../resume. 0 removes the cap.", "tags": [ "outcome" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/outcome/orgs/{org_id}/outcomes/{id}/change": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "message": { "description": "What to change about the spec, in plain words.", "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "description": "The feedback", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "MESSAGE_REQUIRED", "OUTCOME_NOT_FOUND", "WRONG_STATUS", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `MESSAGE_REQUIRED` — Send message: what to change about the spec. Nothing was replanned or charged.; `OUTCOME_NOT_FOUND` — No outcome with that id in this org.; `WRONG_STATUS` — Only an outcome with a ready spec can be changed. Read it with GET.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Ask for the spec to be different; the outcome replans with your feedback folded in (charged like a plan).", "tags": [ "outcome" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/outcome/orgs/{org_id}/outcomes/{id}/code": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "from": { "description": "Ref to branch from (default main).", "type": "string" }, "instructions": { "description": "What to build, in plain words; the agent reads the repo itself.", "type": "string" }, "repo": { "description": "A repo in this org (see /git).", "type": "string" }, "test": { "description": "Test command the sandbox runs after each change, if the project has one.", "type": "string" } }, "required": [ "repo", "instructions" ], "type": "object" } } }, "description": "What to build", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "CODE_STEP_INVALID", "NOT_WORKING", "CODE_SANDBOX_UNAVAILABLE", "CODE_BRANCH_FAILED", "CODE_RUN_FAILED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `CODE_STEP_INVALID` — Send repo and instructions. Nothing was run.; `NOT_WORKING` — The coding step runs only inside a working outcome.; `CODE_SANDBOX_UNAVAILABLE` — No code sandbox is provisioned here. The step was NOT run.; `CODE_BRANCH_FAILED` — The outcome's branch could not be created — see the message. Nothing was run.; `CODE_RUN_FAILED` — The coding step did not finish — the message names why; the branch keeps what landed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "The coding step: build the pages or logic the user sees, in a sandbox, on the outcome's own branch (out/\u003cid\u003e) of a repo in this org, with a per-run key attenuated to the plan's services and capped at the outcome's budget. Only meaningful as a step inside a working outcome. Refused honestly (CODE_SANDBOX_UNAVAILABLE) where no sandbox is provisioned — nothing is pretended.", "tags": [ "outcome" ], "x-safety": { "denylist": false, "kind": "mutate", "proof": [ "ci" ], "reversible": false, "risk": "high" } } }, "/outcome/orgs/{org_id}/outcomes/{id}/experiment": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "hypothesis": { "description": "What you believe, in one sentence. Example: \"indie founders will join a waitlist for invoice chasing\".", "type": "string" }, "stop_rule": { "description": "When it stops. Rules are OR-ed: the first that fires stops it and names itself.", "properties": { "after_days": { "description": "Stop after this many days, 1..365.", "type": "integer" }, "max_spend_cents": { "description": "A spend ceiling in cents, counted from the charges attributed to this run.", "type": "integer" }, "min_events": { "description": "The success stop: enough real people did one thing.", "properties": { "count": { "description": "How many, 1..100000.", "type": "integer" }, "kind": { "description": "An event a real person causes: offer.waitlisted, offer.clicked_buy, offer.preordered, comment.submitted, referral.converted, email.replied, payment.succeeded. Test events never count.", "type": "string" } }, "type": "object" } }, "type": "object" }, "teaches": { "description": "What a result tells you either way — including a zero result.", "type": "string" } }, "required": [ "hypothesis", "teaches", "stop_rule" ], "type": "object" } } }, "description": "The three facts", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "HYPOTHESIS_REQUIRED", "TEACHES_REQUIRED", "STOP_RULE_INVALID", "OUTCOME_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `HYPOTHESIS_REQUIRED` — Send hypothesis: what you believe, in one sentence. Nothing was changed.; `TEACHES_REQUIRED` — Send teaches: what a result tells you either way. Nothing was changed.; `STOP_RULE_INVALID` — The stop rule is empty, out of range, or names an event kind no person causes. Nothing was changed.; `OUTCOME_NOT_FOUND` — No outcome with that id in this org, or it has already stopped.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Make an outcome an experiment: say what you believe (hypothesis), when to stop (stop_rule), and what a result teaches you either way (teaches). The stop rule is written BEFORE the work starts and is checked by the platform, so a zero result is a finding rather than a surprise, and the sentence you read is generated from the rule and cannot drift from what runs. Changes nothing else about the outcome and never re-plans it.", "tags": [ "outcome" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/outcome/orgs/{org_id}/outcomes/{id}/keep": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_KEEPABLE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_KEEPABLE` — Only a partly_done outcome can be kept. Read it with GET.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Accept a partly_done outcome as it stands: what was delivered stays, the failed claims are recorded with their evidence, status becomes done.", "tags": [ "outcome" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/outcome/orgs/{org_id}/outcomes/{id}/pause": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_PAUSABLE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_PAUSABLE` — Only a working outcome can pause.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Pause a working outcome at its next step boundary; the step in flight finishes. Continue with POST .../resume.", "tags": [ "outcome" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/outcome/orgs/{org_id}/outcomes/{id}/resume": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_RESUMABLE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_RESUMABLE` — Only a paused, needs_attention or partly_done outcome can resume. Read it with GET.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Re-run an outcome from its first unfinished step, after fixing the cause of a failure — or continue a paused one, or re-verify a partly_done one (failed claims re-run; DNS and edge propagation often just need time). Completed steps are never repeated.", "tags": [ "outcome" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "high" } } }, "/outcome/orgs/{org_id}/outcomes/{id}/undo": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "OUTCOME_NOT_FOUND", "NOT_UNDOABLE", "NOTHING_TO_UNDO", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `OUTCOME_NOT_FOUND` — No outcome with that id in this org.; `NOT_UNDOABLE` — Only an outcome that has run can be undone. Read it with GET.; `NOTHING_TO_UNDO` — Nothing this outcome did can be reversed; the message lists why.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Generate the undo of an outcome that has run: a NEW outcome whose plan reverses what the original did — restore the previous page version, delete what was created, re-activate the previous schema version — plus a plain-words list of what cannot be undone (messages already sent, money already spent). Nothing is reversed by this call: read the new outcome, then agree to it. Data your app produced since is never touched.", "tags": [ "outcome" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/outreach/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of outreach: method, path, auth, params, error codes — public, no auth", "tags": [ "outreach" ] } }, "/outreach/orgs/{org_id}/sequences": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List sequences, newest first.", "tags": [ "outreach" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "experiment_id": { "description": "Optional tag carried on the sequence so its cost and replies can be attributed.", "type": "string" }, "from_address": { "description": "A mailbox on this account with sending activated. One sequence sends from one address.", "type": "string" }, "name": { "description": "Identifies the sequence in listings.", "type": "string" }, "source_kind": { "description": "Where people come from: crm_query (a CRM contact filter) or list (explicit addresses).", "type": "string" }, "source_ref": { "description": "For crm_query, the filter (stage, origin, company_id, audience_id, min/max_last_engagement_days). For list, {addresses: [...], provenance: founder_contacts | signups | licensed_dataset | replied_before}.", "properties": { "addresses": { "description": "The addresses (list source).", "items": { "description": "Email address", "type": "string" }, "type": "array" }, "provenance": { "description": "Where the addresses came from. Required for a list; scraped is refused.", "type": "string" } }, "type": "object" }, "steps": { "description": "1 to 3 steps, in order.", "items": { "description": "One step", "properties": { "days_after_previous": { "description": "Days to wait after the previous step (at least 1; ignored on the first step).", "type": "integer" }, "template_id": { "description": "A template in this org, from GET /email/orgs/{org_id}/templates.", "type": "string" } }, "type": "object" }, "type": "array" }, "test": { "description": "Test mode: every step goes to the ACCOUNT OWNER instead of the person, subject marked [TEST]. A reply from the owner stops the person exactly as a real reply would. Default false.", "type": "boolean" } }, "required": [ "name", "from_address", "source_kind", "steps" ], "type": "object" } } }, "description": "The sequence", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_JSON", "NAME_REQUIRED", "FROM_ADDRESS_NOT_SENDING", "SOURCE_KIND_REQUIRED", "SOURCE_KIND_UNSUPPORTED", "SOURCE_REF_INVALID", "LIST_PROVENANCE_REQUIRED", "LIST_SCRAPED_REFUSED", "STEPS_INVALID", "STEP_GAP_INVALID", "TEMPLATE_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_JSON` — The request body is not valid JSON.; `NAME_REQUIRED` — name cannot be empty.; `FROM_ADDRESS_NOT_SENDING` — from_address must be a mailbox on this account with sending activated.; `SOURCE_KIND_REQUIRED` — source_kind must be crm_query or list.; `SOURCE_KIND_UNSUPPORTED` — That source is not supported yet.; `SOURCE_REF_INVALID` — source_ref does not describe the named source.; `LIST_PROVENANCE_REQUIRED` — A list must say where the addresses came from. Nothing was created.; `LIST_SCRAPED_REFUSED` — Scraped lists are not sent to. Nothing was created.; `STEPS_INVALID` — steps must have 1 to 3 entries.; `STEP_GAP_INVALID` — days_after_previous must be at least 1 after the first step.; `TEMPLATE_NOT_FOUND` — Every step's template_id must name a template in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create an outreach sequence: up to 3 emails, days apart, that stop for a person as soon as they reply. Nothing is sent until you resolve it and then start it. A list source must say where the addresses came from; scraped lists are refused.", "tags": [ "outreach" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low", "test_mode": true } } }, "/outreach/orgs/{org_id}/sequences/{id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SEQUENCE_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SEQUENCE_NOT_FOUND` — No sequence with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "One sequence with its stats: people by state, who stopped and why, and per step how many were sent and how many answered.", "tags": [ "outreach" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/outreach/orgs/{org_id}/sequences/{id}/cancel": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SEQUENCE_NOT_FOUND", "SEQUENCE_FINISHED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SEQUENCE_NOT_FOUND` — No sequence with that id in this org.; `SEQUENCE_FINISHED` — The sequence is already completed or cancelled.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Stop the sequence for good. Steps not yet sent are not sent; what was sent stays sent.", "tags": [ "outreach" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/outreach/orgs/{org_id}/sequences/{id}/pause": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SEQUENCE_NOT_FOUND", "SEQUENCE_NOT_ACTIVE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SEQUENCE_NOT_FOUND` — No sequence with that id in this org.; `SEQUENCE_NOT_ACTIVE` — Only an active sequence can be paused.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Pause sending. Nothing goes out until you resume; each person's clock keeps its place.", "tags": [ "outreach" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "POST /outreach/orgs/{org_id}/sequences/{id}/resume", "reversible": true, "risk": "low" } } }, "/outreach/orgs/{org_id}/sequences/{id}/replies": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Replies per page (1..200, default 50).", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Rows to skip; meta.next_cursor carries the next offset.", "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SEQUENCE_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SEQUENCE_NOT_FOUND` — No sequence with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "The replies people sent to this sequence, newest first, each with the step it answers and a sentiment (positive, neutral, negative, unsubscribe).", "tags": [ "outreach" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/outreach/orgs/{org_id}/sequences/{id}/resolve": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SEQUENCE_NOT_FOUND", "SEQUENCE_NOT_RESOLVABLE", "NOT_READY", "RESOLVE_FAILED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SEQUENCE_NOT_FOUND` — No sequence with that id in this org.; `SEQUENCE_NOT_RESOLVABLE` — Only a draft or ready sequence can be resolved.; `NOT_READY` — The server is still starting. Retry in a moment.; `RESOLVE_FAILED` — The recipient set could not be built; the message names why.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Turn the source into a frozen list of people and report who it reaches, how many are excluded and why, and what every step to every person would cost. Nothing is sent.", "tags": [ "outreach" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/outreach/orgs/{org_id}/sequences/{id}/resume": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SEQUENCE_NOT_FOUND", "SEQUENCE_NOT_PAUSED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SEQUENCE_NOT_FOUND` — No sequence with that id in this org.; `SEQUENCE_NOT_PAUSED` — Only a paused sequence can be resumed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Resume a paused sequence.", "tags": [ "outreach" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/outreach/orgs/{org_id}/sequences/{id}/start": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SEQUENCE_NOT_FOUND", "SEQUENCE_NOT_STARTABLE", "NO_RECIPIENTS", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SEQUENCE_NOT_FOUND` — No sequence with that id in this org.; `SEQUENCE_NOT_STARTABLE` — Resolve the sequence first.; `NO_RECIPIENTS` — The resolved set is empty, so there is nothing to send.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Begin the sequence. Step 1 sends at the mailbox's safe daily rate, so a sequence commonly runs for days; later steps follow each person's own clock. A reply stops that person's sequence. Every message carries a one-click unsubscribe.", "tags": [ "outreach" ], "x-safety": { "denylist": true, "disclosure": "messages_to_people", "kind": "mutate", "reversible": false, "risk": "high", "test_mode": true } } }, "/payments/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of payments: method, path, auth, params, error codes — public, no auth", "tags": [ "payments" ] } }, "/payments/orgs/{org_id}/charges": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List charges for the org", "tags": [ "payments" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Retry-safety token. Sending the same key within 24h returns the original Checkout URL instead of creating a second Stripe Checkout Session. Use a fresh UUID per logical operation; same UUID for any retry of that operation.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "amount_cents": { "description": "Amount in cents", "type": "integer" }, "currency": { "description": "ISO currency, default usd", "type": "string" }, "description": { "description": "Line-item description", "type": "string" }, "email": { "description": "Customer email (optional)", "type": "string" }, "every": { "description": "Subscription interval (omit for one-off)", "enum": [ "month", "year" ], "type": "string" } }, "required": [ "amount_cents" ], "type": "object" } } }, "description": "Charge payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NOT_CONNECTED", "CHECKOUT_FAILED", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENCY_KEY_IN_FLIGHT", "IDEMPOTENCY_UNAVAILABLE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NOT_CONNECTED` — This org has no connected payment account. Connect one first.; `CHECKOUT_FAILED` — The payment provider refused to create the checkout. No charge was made.; `IDEMPOTENCY_KEY_REUSED` — This Idempotency-Key was already used with different parameters.; `IDEMPOTENCY_KEY_IN_FLIGHT` — A request with this Idempotency-Key is still running. This request was NOT performed — retry shortly to read the first response.; `IDEMPOTENCY_UNAVAILABLE` — The idempotency store could not be read or written, so the request was NOT performed. Retry with the same Idempotency-Key.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a charge — returns a hosted Stripe Checkout URL. `every` (month|year) makes it a subscription. Supports Idempotency-Key header for retry safety (24h TTL).", "tags": [ "payments" ], "x-safety": { "denylist": true, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/payments/orgs/{org_id}/charges/{id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single charge", "tags": [ "payments" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/payments/orgs/{org_id}/charges/{id}/refund": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Full refund of a charge", "tags": [ "payments" ], "x-safety": { "denylist": true, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/payments/orgs/{org_id}/connect": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get the org's Stripe connection status", "tags": [ "payments" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "stripe_secret_key": { "description": "T0: your Stripe secret key (sk_...)", "type": "string" }, "tier": { "description": "Onboarding tier", "enum": [ "t0", "t1" ], "type": "string" } }, "required": [ "tier" ], "type": "object" } } }, "description": "Connect payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Connect Stripe (T0: paste your own secret key — validated, stored in our encrypted secret store). T1 returns 501.", "tags": [ "payments" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/payments/webhook/{org_id}": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Stripe webhook receiver for an org's payments (public, signature-verified)", "tags": [ "payments" ] } }, "/people/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of people: method, path, auth, params, error codes — public, no auth", "tags": [ "people" ] } }, "/people/orgs/{org_id}/search": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "confidence": { "description": "Goldfox confidence tier(s): high (default — 96.4% of dataset, no UGC), low (UGC source — spot-check), very_low (UGC + freemail mismatch — probably drop). Pass explicit array to widen beyond the default high-only.", "items": { "description": "tier", "type": "string" }, "type": "array" }, "country": { "description": "Filter by ISO 3166-1 alpha-2 country code (e.g. US, DE, GB). Consensus across TLD + address + phone.", "items": { "description": "country code", "type": "string" }, "type": "array" }, "country_consistent": { "description": "If true, only rows where TLD + address + phone all agree on country. Highest-trust geo signal.", "type": "boolean" }, "email_type": { "description": "Filter by email_type: corporate / freemail / role_based / other_corporate. OR within array. (Ignored on /company/search.)", "items": { "description": "type", "type": "string" }, "type": "array" }, "has_c_level": { "description": "Row has ≥1 person with seniority = c_level.", "type": "boolean" }, "has_careers_page": { "description": "Row has /careers, /jobs, /stellen, /recrut, /karriere on at least one source URL — growth-stage proxy.", "type": "boolean" }, "has_decision_maker": { "description": "Row has ≥1 person with seniority IN (c_level, vp_director).", "type": "boolean" }, "has_investors_page": { "description": "Row has /investors or /ir/ — public-company / mature-org proxy.", "type": "boolean" }, "has_shop_page": { "description": "Row has /shop, /store, /products, /cart — e-commerce proxy.", "type": "boolean" }, "is_registered_entity": { "description": "companies[0].legal_form_country is not null — name has a recognised legal suffix (GmbH/Ltd/Inc/SARL/...).", "type": "boolean" }, "keyword": { "description": "Case-insensitive substring match on the row's domain.", "type": "string" }, "limit": { "description": "Max results to return (default 20, max 100).", "type": "integer" }, "min_headcount": { "description": "Row's headcount_lower_bound (= ARRAY_LENGTH(people)) must be at least this. Soft floor only — real headcount is usually larger.", "type": "integer" }, "min_link_confidence": { "description": "Drop people with link_confidence below this threshold (0–1). 1.0 = email-domain match (definitive); 0.5 = strong; lower = weak. Default: no threshold.", "type": "integer" }, "min_source_count": { "description": "Row must appear in at least this many distinct source URLs.", "type": "integer" }, "offset": { "description": "Offset for pagination (default 0).", "type": "integer" }, "seniority": { "description": "Filter by Goldfox seniority: c_level, vp_director, manager, senior_ic, ic. OR within array. (Ignored on /company/search.)", "items": { "description": "seniority", "type": "string" }, "type": "array" }, "tld_class": { "description": "Filter by TLD class: cctld / generic / vanity / low_trust / other.", "items": { "description": "class", "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "People search filter (Goldfox-native vocabulary)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Search people in the Goldfox dataset by seniority / link_confidence / country / org signals", "tags": [ "people" ], "x-safety": { "denylist": false, "disclosure": "money", "kind": "mutate", "reversible": false, "risk": "high" } } }, "/people/orgs/{org_id}/{person_id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "person_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "PERSON_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `PERSON_NOT_FOUND` — No person with that id.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single person by id (id format: p_\u003cb64url(domain)\u003e.\u003cindex\u003e; ids come from search results)", "tags": [ "people" ] } }, "/pixel/event": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "event_type": { "description": "One of sent, open, click, page_visit.", "type": "string" }, "meta": { "description": "Arbitrary string metadata (e.g. campaign_id, url).", "type": "string" }, "pixel_id": { "description": "The visitor's pixel id.", "type": "string" } }, "required": [ "pixel_id", "event_type" ], "type": "object" } } }, "description": "Email event", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Record an email-lifecycle event (sent/open/click/page_visit). Public.", "tags": [ "pixel" ] } }, "/pixel/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of pixel: method, path, auth, params, error codes — public, no auth", "tags": [ "pixel" ] } }, "/pixel/orgs/{org_id}/audience/get_geo_sample": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "A domain the org owns. REQUIRED — the sample is scoped to it.", "in": "query", "name": "website", "required": true, "schema": { "type": "string" } }, { "description": "Start of the window (RFC3339). Defaults to the last 30 days.", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "Countries to return (1..200, default 50).", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Country distribution of visits to a website you own, most-visited first.", "tags": [ "pixel" ] } }, "/pixel/orgs/{org_id}/events": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Restrict to one domain.", "in": "query", "name": "domain", "required": false, "schema": { "type": "string" } }, { "description": "Restrict to one campaign.", "in": "query", "name": "campaign_id", "required": false, "schema": { "type": "string" } }, { "description": "Start of the time window, RFC3339 (inclusive).", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "End of the time window, RFC3339 (inclusive).", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } }, { "description": "Rows per page (1..200, default 50). Out-of-range values are clamped; meta.has_more tells you whether the answer was cut short.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Rows to skip (0..100000, default 0). This list pages by offset, not a cursor.", "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Read funnel events.", "tags": [ "pixel" ] } }, "/pixel/orgs/{org_id}/identify": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "description": "The now-known email to attach to that pixel (optional if external_id is set).", "type": "string" }, "external_id": { "description": "The app's own stable user id — e.g. the my-auth end_user id — to attach to that pixel (optional if email is set).", "type": "string" }, "pixel_id": { "description": "The anonymous visitor's pixel id (from fp.js / the pixel cookie).", "type": "string" } }, "required": [ "pixel_id" ], "type": "object" } } }, "description": "Identify payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Link a known identity to an anonymous pixel (identify): call it on form submit or right after the visitor signs in, so their whole anonymous graph resolves to that identity. Provide email and/or external_id (e.g. the my-auth end_user id).", "tags": [ "pixel" ] } }, "/pixel/orgs/{org_id}/identity/{id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "A domain the org owns. REQUIRED — the lookup is scoped to it.", "in": "query", "name": "website", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Resolve a pixel identity. The lookup is scoped to the given website.", "tags": [ "pixel" ] } }, "/pixel/orgs/{org_id}/interactions": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Restrict to one website the org owns.", "in": "query", "name": "website", "required": false, "schema": { "type": "string" } }, { "description": "Restrict to one visited domain.", "in": "query", "name": "domain", "required": false, "schema": { "type": "string" } }, { "description": "Restrict to one campaign.", "in": "query", "name": "campaign_id", "required": false, "schema": { "type": "string" } }, { "description": "Start of the time window (inclusive).", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "End of the time window (inclusive).", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } }, { "description": "Bot traffic is INCLUDED by default; pass `false` to exclude it.", "in": "query", "name": "include_bots", "required": false, "schema": { "type": "boolean" } }, { "description": "Rows per page (1..200, default 50). Out-of-range values are clamped.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Rows to skip (0..100000, default 0).", "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Read pixel interactions for the org.", "tags": [ "pixel" ] } }, "/pixel/orgs/{org_id}/visits": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Restrict to one website the org owns.", "in": "query", "name": "website", "required": false, "schema": { "type": "string" } }, { "description": "Start of the time window, RFC3339 (inclusive).", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "End of the time window, RFC3339 (inclusive).", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } }, { "description": "Rows per page (1..200, default 50). Out-of-range values are clamped; meta.has_more tells you whether the answer was cut short.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Rows to skip (0..100000, default 0). This list pages by offset, not a cursor.", "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Read funnel visits.", "tags": [ "pixel" ] } }, "/pixel/track": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "event_name": { "description": "The event name (e.g. engagement).", "type": "string" }, "pixel_id": { "description": "The visitor's pixel id.", "type": "string" }, "props": { "additionalProperties": true, "description": "Event properties as an object of string values, e.g. {\"dwell_ms\":\"8400\",\"scroll_pct\":\"72\"}.", "type": "object" }, "session_id": { "description": "A client-supplied session id.", "type": "string" }, "url": { "description": "The page URL the event happened on.", "type": "string" } }, "required": [ "pixel_id", "event_name" ], "type": "object" } } }, "description": "Usage event", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_PROPS" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_PROPS` — props must be an object of string values, e.g. {\"dwell_ms\":\"8400\"}. Nothing was recorded." } }, "summary": "Record a usage/engagement event (beacon). Public.", "tags": [ "pixel" ] } }, "/pixel/track.gif": { "get": { "parameters": [ { "description": "The visitor's pixel id.", "in": "query", "name": "pid", "required": false, "schema": { "type": "string" } }, { "description": "The event name.", "in": "query", "name": "e", "required": false, "schema": { "type": "string" } }, { "description": "The page URL the event happened on.", "in": "query", "name": "u", "required": false, "schema": { "type": "string" } }, { "description": "A client-supplied session id.", "in": "query", "name": "sid", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Image-beacon variant of the usage event. Always returns a 1×1 gif.", "tags": [ "pixel" ] } }, "/pixel/visit": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "description": "A known email to stitch to this pixel (deterministic identity).", "type": "string" }, "form_data": { "description": "Submitted form fields to stitch (email/phone/name/…).", "type": "string" }, "page_url": { "description": "The URL being visited.", "type": "string" }, "pixel_id": { "description": "The visitor's pixel id; omit for a new visitor (a new id is minted).", "type": "string" }, "referrer": { "description": "The referring URL, if any.", "type": "string" } }, "type": "object" } } }, "description": "Visit beacon", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Record a pixel visit (beacon). Public; called by the pixel script.", "tags": [ "pixel" ] } }, "/queue/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of queue: method, path, auth, params, error codes — public, no auth", "tags": [ "queue" ] } }, "/queue/orgs/{org_id}/jobs/{id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A queue job", "properties": { "attempt": { "description": "Dispatch attempts so far", "type": "integer" }, "created_at": { "description": "RFC3339 creation time", "type": "string" }, "dedup_key": { "description": "Idempotency key (omitted when unset)", "type": "string" }, "depends_on": { "description": "Job ids this job waits on", "items": { "description": "A job id", "type": "string" }, "type": "array" }, "id": { "description": "Job id", "type": "string" }, "last_error": { "description": "Last dispatch error (omitted when unset)", "type": "string" }, "max_attempts": { "description": "Retries before dead-letter (copied from the queue at enqueue)", "type": "integer" }, "not_before": { "description": "RFC3339 — not eligible to run before this", "type": "string" }, "org_id": { "description": "Owning org id", "type": "string" }, "payload": { "additionalProperties": true, "description": "Arbitrary JSON delivered to the consumer", "type": "object" }, "queue_id": { "description": "Owning queue id", "type": "string" }, "started_at": { "description": "RFC3339 — when the current run started (omitted when unset)", "type": "string" }, "status": { "description": "Lifecycle state", "enum": [ "pending", "blocked", "running", "succeeded", "dead" ], "type": "string" }, "updated_at": { "description": "RFC3339 last-update time", "type": "string" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single job's status.", "tags": [ "queue" ] } }, "/queue/orgs/{org_id}/queues": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Rows per page (1..500, default 50). Out-of-range values are rejected with 400 rather than clamped — a caller who asks for 5000 and silently gets 500 believes they have the whole list.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Keyset cursor — pass the previous page's meta.next_cursor. Absent on the last page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Queue list", "properties": { "queues": { "description": "The org's queues", "items": { "description": "A queue", "properties": { "consumer_url": { "description": "HTTP endpoint each job is POSTed to", "type": "string" }, "created_at": { "description": "RFC3339 creation time", "type": "string" }, "id": { "description": "Queue id", "type": "string" }, "max_attempts": { "description": "Retries before a job dead-letters", "type": "integer" }, "max_concurrency": { "description": "Max jobs dispatched at once", "type": "integer" }, "name": { "description": "Queue name (unique per org)", "type": "string" }, "org_id": { "description": "Owning org id", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List queues for the org.", "tags": [ "queue" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "consumer_url": { "description": "HTTP(S) endpoint each job payload is POSTed to. A 2xx succeeds the job.", "type": "string" }, "max_attempts": { "description": "Retries before a job dead-letters (default 5).", "type": "integer" }, "max_concurrency": { "description": "Max jobs dispatched at once (default 5).", "type": "integer" }, "name": { "description": "Queue name, unique per org (max 64 chars).", "type": "string" } }, "required": [ "name", "consumer_url" ], "type": "object" } } }, "description": "Queue creation payload", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A queue", "properties": { "consumer_url": { "description": "HTTP endpoint each job is POSTed to", "type": "string" }, "created_at": { "description": "RFC3339 creation time", "type": "string" }, "id": { "description": "Queue id", "type": "string" }, "max_attempts": { "description": "Retries before a job dead-letters", "type": "integer" }, "max_concurrency": { "description": "Max jobs dispatched at once", "type": "integer" }, "name": { "description": "Queue name (unique per org)", "type": "string" }, "org_id": { "description": "Owning org id", "type": "string" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a named queue with its retry + concurrency policy and the HTTP consumer that runs its jobs.", "tags": [ "queue" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /queue/orgs/{org_id}/queues/{name}", "reversible": true, "risk": "low" } } }, "/queue/orgs/{org_id}/queues/{name}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete a queue and all its jobs (cascade).", "tags": [ "queue" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } }, "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A queue", "properties": { "consumer_url": { "description": "HTTP endpoint each job is POSTed to", "type": "string" }, "created_at": { "description": "RFC3339 creation time", "type": "string" }, "id": { "description": "Queue id", "type": "string" }, "max_attempts": { "description": "Retries before a job dead-letters", "type": "integer" }, "max_concurrency": { "description": "Max jobs dispatched at once", "type": "integer" }, "name": { "description": "Queue name (unique per org)", "type": "string" }, "org_id": { "description": "Owning org id", "type": "string" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single queue.", "tags": [ "queue" ] }, "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "consumer_url": { "description": "New HTTP consumer URL for the queue's jobs.", "type": "string" }, "max_attempts": { "description": "Max delivery attempts per job (positive).", "type": "integer" }, "max_concurrency": { "description": "Max concurrent in-flight jobs (positive).", "type": "integer" } }, "type": "object" } } }, "description": "Queue config patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Update a queue's config in place (consumer_url, max_attempts, max_concurrency) without deleting it — the name and its jobs are kept. Provide at least one field.", "tags": [ "queue" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/queue/orgs/{org_id}/queues/{name}/jobs": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "description": "Jobs per page (1..200, default 50). Out-of-range values are rejected with 400.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Filter by job status.", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Job list", "properties": { "jobs": { "description": "The queue's jobs, newest first", "items": { "description": "A queue job", "properties": { "attempt": { "description": "Dispatch attempts so far", "type": "integer" }, "created_at": { "description": "RFC3339 creation time", "type": "string" }, "dedup_key": { "description": "Idempotency key (omitted when unset)", "type": "string" }, "depends_on": { "description": "Job ids this job waits on", "items": { "description": "A job id", "type": "string" }, "type": "array" }, "id": { "description": "Job id", "type": "string" }, "last_error": { "description": "Last dispatch error (omitted when unset)", "type": "string" }, "max_attempts": { "description": "Retries before dead-letter (copied from the queue at enqueue)", "type": "integer" }, "not_before": { "description": "RFC3339 — not eligible to run before this", "type": "string" }, "org_id": { "description": "Owning org id", "type": "string" }, "payload": { "additionalProperties": true, "description": "Arbitrary JSON delivered to the consumer", "type": "object" }, "queue_id": { "description": "Owning queue id", "type": "string" }, "started_at": { "description": "RFC3339 — when the current run started (omitted when unset)", "type": "string" }, "status": { "description": "Lifecycle state", "enum": [ "pending", "blocked", "running", "succeeded", "dead" ], "type": "string" }, "updated_at": { "description": "RFC3339 last-update time", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List a queue's jobs, newest first. Filters: status, limit (1-200).", "tags": [ "queue" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "dedup_key": { "description": "Optional idempotency key; a repeated key returns the existing job.", "type": "string" }, "delay_seconds": { "description": "Delay before the job becomes eligible to run.", "type": "integer" }, "depends_on": { "description": "Job ids this job waits on. Immutable — DAG by construction.", "items": { "description": "A job id", "type": "string" }, "type": "array" }, "payload": { "additionalProperties": true, "description": "Arbitrary JSON POSTed to the queue's consumer (max 256 KB).", "type": "object" } }, "type": "object" } } }, "description": "Job enqueue payload", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A queue job", "properties": { "attempt": { "description": "Dispatch attempts so far", "type": "integer" }, "created_at": { "description": "RFC3339 creation time", "type": "string" }, "dedup_key": { "description": "Idempotency key (omitted when unset)", "type": "string" }, "depends_on": { "description": "Job ids this job waits on", "items": { "description": "A job id", "type": "string" }, "type": "array" }, "id": { "description": "Job id", "type": "string" }, "last_error": { "description": "Last dispatch error (omitted when unset)", "type": "string" }, "max_attempts": { "description": "Retries before dead-letter (copied from the queue at enqueue)", "type": "integer" }, "not_before": { "description": "RFC3339 — not eligible to run before this", "type": "string" }, "org_id": { "description": "Owning org id", "type": "string" }, "payload": { "additionalProperties": true, "description": "Arbitrary JSON delivered to the consumer", "type": "object" }, "queue_id": { "description": "Owning queue id", "type": "string" }, "started_at": { "description": "RFC3339 — when the current run started (omitted when unset)", "type": "string" }, "status": { "description": "Lifecycle state", "enum": [ "pending", "blocked", "running", "succeeded", "dead" ], "type": "string" }, "updated_at": { "description": "RFC3339 last-update time", "type": "string" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Enqueue a job. Idempotent on (queue, dedup_key) — a repeated key returns the existing job at 200. A job with unsucceeded depends_on starts blocked.", "tags": [ "queue" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/referral/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of referral: method, path, auth, params, error codes — public, no auth", "tags": [ "referral" ] } }, "/referral/orgs/{org_id}/programs": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List referral programs, newest first.", "tags": [ "referral" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reward": { "description": "{kind, value}", "properties": { "kind": { "description": "credit_cents, discount_percent or cash_share_percent.", "type": "string" }, "value": { "description": "Cents for credit_cents; a percent from 1 to 100 for the other two.", "type": "integer" } }, "type": "object" }, "target": { "description": "The page a referred visitor lands on (absolute http or https URL). It receives ?src=\u003ccode\u003e.", "type": "string" }, "terms_text": { "description": "When and how you pay referrers. Required for cash_share_percent.", "type": "string" } }, "required": [ "target", "reward" ], "type": "object" } } }, "description": "The program", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_TARGET", "REWARD_INVALID", "TERMS_REQUIRED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_TARGET` — target is not an absolute http or https URL. Nothing was created.; `REWARD_INVALID` — reward.kind or reward.value is not usable — see the message. Nothing was created.; `TERMS_REQUIRED` — A cash share needs terms_text. Nothing was created.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a referral program: give every customer a link to target. When someone they send pays, the referrer is owed what you promise — a credit, a discount on their next payment, or a share of the payment you pay out yourself. We keep the ledger; we never move the money.", "tags": [ "referral" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/referral/orgs/{org_id}/programs/{id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "PROGRAM_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `PROGRAM_NOT_FOUND` — No program with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Read one program with its numbers: referrers, referred visits (bots excluded), referred payers, rewards owed and paid. Test payments are counted separately and never owe a reward.", "tags": [ "referral" ] } }, "/referral/orgs/{org_id}/programs/{id}/links": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "description": "The referrer's email address.", "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "description": "The referrer", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "PROGRAM_NOT_FOUND", "EMAIL_REQUIRED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `PROGRAM_NOT_FOUND` — No program with that id in this org.; `EMAIL_REQUIRED` — Send email: the referrer's address. Nothing was created.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Make a referral link for one customer. The link opens target with ?src=\u003ccode\u003e; pass that src when you create the checkout and the payment is attributed to them. Asking again for the same email returns the same link (200).", "tags": [ "referral" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/referral/orgs/{org_id}/programs/{id}/payouts": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "PROGRAM_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `PROGRAM_NOT_FOUND` — No program with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "The ledger: one row per attributed payment with the reward owed, paid or reversed (refunded), plus what is owed per referrer. You pay referrers yourself and mark rows paid.", "tags": [ "referral" ] } }, "/referral/orgs/{org_id}/programs/{id}/payouts/{payout_id}/mark-paid": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "payout_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "PROGRAM_NOT_FOUND", "PAYOUT_NOT_FOUND", "NOT_OWED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `PROGRAM_NOT_FOUND` — No program with that id in this org.; `PAYOUT_NOT_FOUND` — No payout with that id in this program.; `NOT_OWED` — The payout is already paid, reversed, or owes nothing. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Record that you paid a referrer for one ledger row. No money moves here.", "tags": [ "referral" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/runner/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of runner: method, path, auth, params, error codes — public, no auth", "tags": [ "runner" ] } }, "/runner/orgs/{org_id}/installations": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INSTALLATIONS_UNREADABLE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INSTALLATIONS_UNREADABLE` — The connected installations could not be read. Try again.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List the GitHub App installations connected to this org. An installation connected to a different org of the same account is not listed here.", "tags": [ "runner" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The single-use OAuth code from the GitHub install redirect. Expires quickly — start the install again to get a new one.", "type": "string" }, "installation_id": { "description": "The GitHub App installation id, as returned in the install redirect. A decimal string is accepted too.", "type": "integer" }, "state": { "description": "The state from POST .../installations/start, returned to you by GitHub on the redirect. Single-use and required: it proves this connection was started by you.", "type": "string" } }, "required": [ "installation_id", "code", "state" ], "type": "object" } } }, "description": "Installation connect payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INSTALLATION_ID_REQUIRED", "CONNECT_CODE_REQUIRED", "GITHUB_CODE_REJECTED", "GITHUB_UNREACHABLE", "CONNECT_NOT_CONFIGURED", "STATE_REQUIRED", "STATE_INVALID", "INSTALLATION_NOT_YOURS", "INSTALLATION_CLAIMED", "CONNECT_NOT_RECORDED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INSTALLATION_ID_REQUIRED` — Pass the installation_id GitHub returned after the install. Nothing was connected.; `CONNECT_CODE_REQUIRED` — Pass the code from the GitHub install redirect. Nothing was connected.; `GITHUB_CODE_REJECTED` — GitHub refused this code. Start the install again to get a new one. Nothing was connected.; `GITHUB_UNREACHABLE` — GitHub did not answer. Try again. Nothing was connected.; `CONNECT_NOT_CONFIGURED` — The GitHub connection is not set up on this deployment. Nothing was connected.; `STATE_REQUIRED` — state is required. Start with POST /runner/orgs/{org_id}/installations/start. Nothing was connected.; `STATE_INVALID` — The connection did not start here, or the state was already used or has expired. Nothing was connected.; `INSTALLATION_NOT_YOURS` — Your GitHub account cannot reach this installation. Nothing was connected.; `INSTALLATION_CLAIMED` — Another account is connected to this installation. Nothing was connected.; `CONNECT_NOT_RECORDED` — The installation was NOT connected. Try again.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Connect a GitHub App installation to this org, so the jobs it sends are attributed and billed to you. Send the installation_id and the code from the GitHub install redirect. The code is what proves the installation is yours: it is exchanged with GitHub for the list of installations your GitHub account can reach, and an installation that is not on that list is refused. Returns 201.", "tags": [ "runner" ] } }, "/runner/orgs/{org_id}/installations/start": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "STATE_NOT_ISSUED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `STATE_NOT_ISSUED` — The connect flow could not be started. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Begin connecting a GitHub App installation. Returns a single-use state, valid for ten minutes, that you pass to GitHub as the state query parameter when installing. It is what proves the connection was started by you: without it, anyone holding your install code could attach your installation to their own organisation. Returns 201.", "tags": [ "runner" ] } }, "/runner/webhooks/github": { "post": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SIGNATURE_INVALID", "INVALID_JSON", "INVALID_BODY", "NOT_RECORDED", "INSTALLATION_NOT_RECORDED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SIGNATURE_INVALID` — The signature did not verify. Nothing was recorded.; `INVALID_JSON` — The payload is not valid JSON. Nothing was recorded.; `INVALID_BODY` — The request body could not be read. Nothing was recorded.; `NOT_RECORDED` — The event was accepted but NOT recorded, so this job will not be watched. GitHub should redeliver.; `INSTALLATION_NOT_RECORDED` — The installation event was accepted but NOT recorded, so jobs from this installation stay unattributed. GitHub should redeliver." } }, "summary": "Receive GitHub Actions events. Authenticated by the X-Hub-Signature-256 HMAC and nothing else — there is no bearer token, and a delivery is refused when no secret is configured rather than accepted. workflow_job records a job, but only when its runs-on includes the myapi label; everything else is acknowledged and ignored, because booking a job we will never serve makes it look stalled forever. installation records that the app was added to, suspended on, or removed from a GitHub account — it never sets an owner, because the payload does not name one.", "tags": [ "runner" ] } }, "/runs/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of runs: method, path, auth, params, error codes — public, no auth", "tags": [ "runs" ] } }, "/runs/orgs/{org_id}/runs": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Only runs for this project.", "in": "query", "name": "project", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List the org's runs, newest first.", "tags": [ "runs" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "key_results": { "description": "Measurable results.", "items": { "additionalProperties": true, "description": "{kr, measure, target}", "type": "object" }, "type": "array" }, "lanes": { "description": "Budget split and concurrency per lane.", "items": { "additionalProperties": true, "description": "{lane, budget_pct, max_concurrent, enabled}", "type": "object" }, "type": "array" }, "name": { "description": "Unique within the org, e.g. morocco-2026-09.", "type": "string" }, "objective": { "description": "What the run is for, in a sentence.", "type": "string" }, "policy": { "additionalProperties": true, "description": "Free-form policy the sessions read: branch_prefix, auto_merge_classes, task_cap_minutes, external_actions.", "type": "object" }, "project": { "description": "Which project this run belongs to, e.g. sabaki.", "type": "string" }, "status": { "description": "draft (default), active, paused or done.", "type": "string" } }, "required": [ "project", "name" ], "type": "object" } } }, "description": "Run payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_REQUEST", "INVALID_STATUS", "INVALID_LANES", "RUN_EXISTS", "RATE_LIMITED", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_REQUEST` — Send project and name. No run was created.; `INVALID_STATUS` — status must be draft, active, paused or done. No run was created.; `INVALID_LANES` — Every lane needs a name and max_concurrent of at least 1. No run was created.; `RUN_EXISTS` — A run with that name already exists in this org. No run was created.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a run: one campaign for one project, with its objective, key results and lanes. Runs are append-only — pause or finish one by status; nothing deletes it. A task can only be claimed while the run is active.", "tags": [ "runs" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/runs/orgs/{org_id}/runs/{run_id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RUN_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RUN_NOT_FOUND` — No run with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Read one run.", "tags": [ "runs" ] } }, "/runs/orgs/{org_id}/runs/{run_id}/digests": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "date": { "description": "YYYY-MM-DD. Default today (UTC).", "type": "string" }, "kr_progress": { "description": "Progress per key result.", "items": { "additionalProperties": true, "description": "{kr, status}", "type": "object" }, "type": "array" }, "needs_simon": { "description": "Task ids waiting on a person.", "items": { "description": "A task id", "type": "string" }, "type": "array" }, "reordered": { "description": "Task ids the plan moved.", "items": { "description": "A task id", "type": "string" }, "type": "array" }, "summary": { "description": "What happened and what is next, for a phone screen.", "type": "string" } }, "required": [ "summary" ], "type": "object" } } }, "description": "Digest payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RUN_NOT_FOUND", "INVALID_REQUEST", "RATE_LIMITED", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RUN_NOT_FOUND` — No run with that id in this org.; `INVALID_REQUEST` — summary is required and date must be YYYY-MM-DD. Nothing was written.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Write the day's digest for a run — the nightly plan's output. One per run per day; writing the same day again replaces it.", "tags": [ "runs" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "POST /runs/orgs/{org_id}/runs/{run_id}/digests", "reversible": true, "risk": "low" } } }, "/runs/orgs/{org_id}/runs/{run_id}/digests/latest": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RUN_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RUN_NOT_FOUND` — No run with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Read the most recent digest for a run — the morning read.", "tags": [ "runs" ] } }, "/runs/orgs/{org_id}/runs/{run_id}/status": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "status": { "description": "draft, active, paused or done.", "type": "string" } }, "required": [ "status" ], "type": "object" } } }, "description": "Status payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RUN_NOT_FOUND", "INVALID_STATUS", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RUN_NOT_FOUND` — No run with that id in this org.; `INVALID_STATUS` — status must be draft, active, paused or done. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Pause, resume or finish a run. Claims are refused while a run is not active, which is how a run is stopped from a phone.", "tags": [ "runs" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "POST /runs/orgs/{org_id}/runs/{run_id}/status", "reversible": true, "risk": "low" } } }, "/runs/orgs/{org_id}/runs/{run_id}/tasks": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string" } }, { "description": "Only tasks in this status.", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "description": "Only tasks in this lane.", "in": "query", "name": "lane", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RUN_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RUN_NOT_FOUND` — No run with that id in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List a run's tasks in claim order (priority, then position). Filter by status or lane — status=needs_simon is the morning phone read.", "tags": [ "runs" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "tasks": { "description": "The tasks to add.", "items": { "description": "A task", "properties": { "budget_minutes": { "description": "Time budget. The lease expires this long plus 15 minutes after the last heartbeat. Default 45.", "type": "string" }, "depends_on": { "description": "Task ids that must be done before this one can be claimed.", "items": { "description": "A task id in the same run", "type": "string" }, "type": "array" }, "description": { "description": "What to do.", "type": "string" }, "done_when": { "description": "Required. What must be true when the task is finished.", "type": "string" }, "files_hint": { "description": "Optional scope fence: paths the task is expected to touch.", "items": { "description": "A path", "type": "string" }, "type": "array" }, "id": { "description": "Stable, human-readable id, e.g. sab-runs-001. Unique within the run.", "type": "string" }, "lane": { "description": "The lane this task is worked in. Must match a lane on the run for concurrency to apply.", "type": "string" }, "priority": { "description": "1, 2 or 3. 1 is claimed first. Default 2.", "type": "string" }, "status": { "description": "Initial status. Default ready.", "type": "string" }, "title": { "description": "One line.", "type": "string" }, "verify": { "description": "Required. The command or checklist that proves done_when.", "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "tasks" ], "type": "object" } } }, "description": "Tasks payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RUN_NOT_FOUND", "INVALID_REQUEST", "TASK_UNVERIFIABLE", "TASK_EXISTS", "RATE_LIMITED", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RUN_NOT_FOUND` — No run with that id in this org.; `INVALID_REQUEST` — tasks must be a non-empty array. Nothing was added.; `TASK_UNVERIFIABLE` — A task is missing done_when or verify, or has an invalid field; the message names it. Nothing was added.; `TASK_EXISTS` — A task with that id already exists in this run. Nothing was added.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Add tasks to a run in one call — the backlog import. Every task must carry done_when and verify; one that does not is refused by id and nothing is added. Ids are yours and must be unique within the run.", "tags": [ "runs" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/runs/orgs/{org_id}/runs/{run_id}/tasks/claim-next": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lanes": { "description": "Only claim from these lanes. Omit for any lane.", "items": { "description": "A lane name", "type": "string" }, "type": "array" }, "session_id": { "description": "The claiming session, recorded on the task as claimed_by.", "type": "string" } }, "required": [ "session_id" ], "type": "object" } } }, "description": "Claim payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RUN_NOT_FOUND", "INVALID_REQUEST", "RUN_NOT_ACTIVE", "RATE_LIMITED", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RUN_NOT_FOUND` — No run with that id in this org.; `INVALID_REQUEST` — Send session_id. Nothing was claimed.; `RUN_NOT_ACTIVE` — The run is paused, draft or done. Nothing was claimed — set it active first.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Claim the next task for a session: the highest-priority ready task whose dependencies are all done, in a lane under its concurrency limit. Atomic — many sessions claiming at once get one task each, never the same one. A task released twice by dead sessions is blocked instead of handed out a third time. Returns task: null with a reason when nothing is ready.", "tags": [ "runs" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "POST /runs/orgs/{org_id}/runs/{run_id}/tasks/{task_id}/release", "reversible": true, "risk": "low" } } }, "/runs/orgs/{org_id}/runs/{run_id}/tasks/reorder": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "task_ids": { "description": "Task ids in the order they should be claimed.", "items": { "description": "A task id", "type": "string" }, "type": "array" } }, "required": [ "task_ids" ], "type": "object" } } }, "description": "Reorder payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RUN_NOT_FOUND", "INVALID_REQUEST", "TASK_NOT_FOUND", "RATE_LIMITED", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RUN_NOT_FOUND` — No run with that id in this org.; `INVALID_REQUEST` — task_ids must be a non-empty array. Nothing was reordered.; `TASK_NOT_FOUND` — A named task is not in this run. Nothing was reordered.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Reorder tasks within their priority: the ids given move to the front in that order; the rest keep their relative order after them. The nightly plan's output.", "tags": [ "runs" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "POST /runs/orgs/{org_id}/runs/{run_id}/tasks/reorder", "reversible": true, "risk": "low" } } }, "/runs/orgs/{org_id}/runs/{run_id}/tasks/{task_id}/heartbeat": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RUN_NOT_FOUND", "TASK_NOT_FOUND", "TASK_NOT_CLAIMED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RUN_NOT_FOUND` — No run with that id in this org.; `TASK_NOT_FOUND` — No task with that id in this run.; `TASK_NOT_CLAIMED` — Only a claimed or in-progress task has a lease. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Extend the lease on a claimed or in-progress task. A task with no heartbeat for budget_minutes + 15 is released to the next session.", "tags": [ "runs" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/runs/orgs/{org_id}/runs/{run_id}/tasks/{task_id}/release": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RUN_NOT_FOUND", "TASK_NOT_FOUND", "TASK_NOT_CLAIMED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RUN_NOT_FOUND` — No run with that id in this org.; `TASK_NOT_FOUND` — No task with that id in this run.; `TASK_NOT_CLAIMED` — The task holds no lease to release. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Give a claimed task back to the queue. The attempt still counts: a task released twice is blocked rather than claimed a third time.", "tags": [ "runs" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "POST /runs/orgs/{org_id}/runs/{run_id}/tasks/claim-next", "reversible": true, "risk": "low" } } }, "/runs/orgs/{org_id}/runs/{run_id}/tasks/{task_id}/report": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "branch": { "description": "The branch the work is on.", "type": "string" }, "commit": { "description": "The commit that carries it.", "type": "string" }, "cost": { "additionalProperties": true, "description": "{minutes, turns}", "type": "object" }, "evidence": { "description": "The verify output, a test summary, or a report path. Required for done.", "type": "string" }, "followups": { "description": "Work this task found. Each becomes a ready task; lane and priority are inherited when omitted; after_parent: true makes it wait on this task.", "items": { "additionalProperties": true, "description": "{title, lane, priority, description, done_when, verify, budget_minutes, depends_on, after_parent}", "type": "object" }, "type": "array" }, "notes": { "description": "Anything the next session should know.", "type": "string" }, "outcome": { "description": "done, blocked, needs_simon or partial.", "type": "string" } }, "required": [ "outcome" ], "type": "object" } } }, "description": "Report payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RUN_NOT_FOUND", "TASK_NOT_FOUND", "INVALID_OUTCOME", "TASK_NOT_CLAIMED", "EVIDENCE_REQUIRED", "TASK_UNVERIFIABLE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RUN_NOT_FOUND` — No run with that id in this org.; `TASK_NOT_FOUND` — No task with that id in this run.; `INVALID_OUTCOME` — outcome must be done, blocked, needs_simon or partial. Nothing was recorded.; `TASK_NOT_CLAIMED` — Only a claimed or in-progress task can be reported on. Nothing was recorded.; `EVIDENCE_REQUIRED` — A done outcome needs evidence. Nothing was recorded.; `TASK_UNVERIFIABLE` — A follow-up is missing done_when or verify; the message names it. Nothing was recorded.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Report a claimed task: the outcome, the evidence, and any follow-ups, which are inserted as ready tasks in one transaction. done needs evidence. Outcomes: done, blocked, needs_simon, partial (the task goes to review).", "tags": [ "runs" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/runs/orgs/{org_id}/runs/{run_id}/tasks/{task_id}/start": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RUN_NOT_FOUND", "TASK_NOT_FOUND", "TASK_NOT_CLAIMED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RUN_NOT_FOUND` — No run with that id in this org.; `TASK_NOT_FOUND` — No task with that id in this run.; `TASK_NOT_CLAIMED` — The task is not claimed. Claim it with claim-next first. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Mark a claimed task in progress. Call it once the session has actually begun the work.", "tags": [ "runs" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "POST /runs/orgs/{org_id}/runs/{run_id}/tasks/{task_id}/release", "reversible": true, "risk": "low" } } }, "/runs/orgs/{org_id}/runs/{run_id}/tasks/{task_id}/status": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "note": { "description": "Why. Shown on the task.", "type": "string" }, "status": { "description": "ready, claimed, in_progress, review, done, blocked, needs_simon or archived.", "type": "string" } }, "required": [ "status" ], "type": "object" } } }, "description": "Status payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RUN_NOT_FOUND", "TASK_NOT_FOUND", "INVALID_STATUS", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RUN_NOT_FOUND` — No run with that id in this org.; `TASK_NOT_FOUND` — No task with that id in this run.; `INVALID_STATUS` — status must be one of the task statuses. Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Set a task's status directly, with a note — the phone control. Unblock a task by setting it ready (its attempt count restarts), archive one, or promote one to needs_simon.", "tags": [ "runs" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "POST /runs/orgs/{org_id}/runs/{run_id}/tasks/{task_id}/status", "reversible": true, "risk": "low" } } }, "/schema/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of schema: method, path, auth, params, error codes — public, no auth", "tags": [ "schema" ] } }, "/schema/v1/docs": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Browsable API reference (Redoc-rendered)", "tags": [ "schema" ] } }, "/schema/v1/openapi.json": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Auto-generated OpenAPI 3.0.3 document — public, CDN-cacheable. Carries a servers entry, so a generated client does not have to guess the host.", "tags": [ "schema" ] } }, "/storage/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of storage: method, path, auth, params, error codes — public, no auth", "tags": [ "storage" ] } }, "/storage/orgs/{org_id}/assets": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Assets per page (1..500, default 50). Out-of-range values are rejected with 400 rather than clamped — a caller who asks for 5000 and silently gets 500 believes they have the whole list.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Keyset cursor — pass the previous page's meta.next_cursor. Absent on the last page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List asset_ingestions for the org (newest first, keyset-paged)", "tags": [ "storage" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/storage/orgs/{org_id}/assets/ingest": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "description": { "description": "Human description of the asset", "type": "string" }, "name": { "description": "Filename to store it under", "type": "string" }, "url": { "description": "Publicly reachable URL to fetch. Private and link-local addresses are rejected.", "type": "string" } }, "required": [ "url" ], "type": "object" } } }, "description": "Asset to fetch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "URL_REQUIRED", "HTTPS_REQUIRED", "RATE_LIMIT_EXCEEDED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `URL_REQUIRED` — Send url in the body. Nothing was ingested.; `HTTPS_REQUIRED` — The url must use https. Nothing was ingested.; `RATE_LIMIT_EXCEEDED` — Too many ingests in a short time. Wait and retry.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Ingest an asset by URL (server-side fetch with SSRF guard). The fetched asset is stored public, because it was already reachable on the public internet; make it private afterwards with PATCH if that is not what you want.", "tags": [ "storage" ], "x-safety": { "denylist": false, "disclosure": "data_visible_publicly", "kind": "mutate", "reversible": false, "risk": "low" } } }, "/storage/orgs/{org_id}/assets/upload": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Asset filename. Used for a raw-body upload, where there is no multipart part to carry it.", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "Optional human description stored with the asset.", "in": "query", "name": "description", "required": false, "schema": { "type": "string" } }, { "description": "\"public\" (default) or \"private\". A public file is readable by ANYONE who has the URL, forever, with no credentials — the id is not a secret and unguessable ids are NOT access control. A private file is served only through a signed link that runs out (POST .../signed-url) and can be revoked. Choose private for anything holding personal data. Used for a raw-body upload, where there is no multipart part to carry it.", "in": "query", "name": "visibility", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "description": { "description": "Human description of the asset", "type": "string" }, "file": { "description": "The asset bytes. Size cap depends on the detected type: images (jpeg/png/gif/webp/svg) 10MB, video (mp4/webm) 200MB, PDF and everything else 25MB. Over the cap the upload is refused with error code FILE_TOO_LARGE. A raw-body (non-multipart) upload is capped at 10MB regardless of type.", "format": "binary", "type": "string" }, "name": { "description": "Filename to store it under", "type": "string" }, "visibility": { "description": "\"public\" (default) or \"private\". A public file is readable by ANYONE who has the URL, forever, with no credentials — the id is not a secret and unguessable ids are NOT access control. A private file is served only through a signed link that runs out (POST .../signed-url) and can be revoked. Choose private for anything holding personal data.", "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "description": "The asset file plus optional metadata", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "FILE_TOO_LARGE", "INVALID_VISIBILITY", "RATE_LIMIT_EXCEEDED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `FILE_TOO_LARGE` — The upload is over the size cap for its detected type. Multipart raises the cap; a raw body is always capped at 10MB.; `INVALID_VISIBILITY` — visibility was neither \"public\" nor \"private\". The file was NOT stored.; `RATE_LIMIT_EXCEEDED` — Too many uploads in a short time. Wait and retry.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Upload an asset directly. ANY content type is accepted — unknown types are stored as opaque blobs, so there is no allowlist to match against. Use multipart/form-data to get the full per-type size limit; a raw-body upload is capped at 10MB whatever the type. Set visibility=private for anything holding personal data: the default is a permanent, unauthenticated URL. A private upload returns no url field, because the plain URL does not serve it — get a signed link instead.", "tags": [ "storage" ], "x-safety": { "denylist": false, "disclosure": "data_visible_publicly", "kind": "mutate", "reversible": false, "risk": "low" } } }, "/storage/orgs/{org_id}/assets/{asset_id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "asset_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Permanently delete an asset and its stored object. Not recoverable.", "tags": [ "storage" ], "x-safety": { "denylist": true, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } }, "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "asset_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "visibility": { "description": "\"public\" (default) or \"private\". A public file is readable by ANYONE who has the URL, forever, with no credentials — the id is not a secret and unguessable ids are NOT access control. A private file is served only through a signed link that runs out (POST .../signed-url) and can be revoked. Choose private for anything holding personal data.", "type": "string" } }, "required": [ "visibility" ], "type": "object" } } }, "description": "New visibility", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_VISIBILITY", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_VISIBILITY` — visibility was neither \"public\" nor \"private\". Nothing was changed.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Change whether a file is public or private. Making a file private takes effect at once: the plain URL stops serving it and only signed links work. Making it public again means anyone with the URL can read it, forever.", "tags": [ "storage" ], "x-safety": { "denylist": false, "disclosure": "data_visible_publicly", "kind": "mutate", "reversible": false, "risk": "low" } } }, "/storage/orgs/{org_id}/assets/{asset_id}/revoke-links": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "asset_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Kill every signed link made for this file. Links already sent out stop working at once, including ones that had not run out yet. Make a new link afterwards for anyone who should still have access. This does nothing for a public file — anyone with the plain URL can still read it.", "tags": [ "storage" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/storage/orgs/{org_id}/assets/{asset_id}/signed-url": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "asset_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "expires_in": { "description": "How long the link works, in seconds. Default 900 (15 minutes), maximum 86400 (24 hours).", "type": "integer" } }, "type": "object" } } }, "description": "Link lifetime", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "ASSET_IS_PUBLIC", "EXPIRES_TOO_LONG", "SIGNING_UNAVAILABLE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `ASSET_IS_PUBLIC` — The file is public, so a signed link would give no protection. Make it private first.; `EXPIRES_TOO_LONG` — expires_in is over the 86400 second maximum. No link was made.; `SIGNING_UNAVAILABLE` — Links cannot be made right now. No link was made and the file is safe.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Make a link that serves a private file for a limited time. The link carries its own authorisation, so it can be sent to someone who has no account. It stops working when it runs out, and every link for the file can be killed early with POST .../revoke-links.", "tags": [ "storage" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/storage/orgs/{org_id}/uploads/begin": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "description": { "description": "Human description stored with the asset.", "type": "string" }, "name": { "description": "Filename to store it under.", "type": "string" }, "visibility": { "description": "\"public\" (default) or \"private\". A public file is readable by ANYONE who has the URL, forever, with no credentials — the id is not a secret and unguessable ids are NOT access control. A private file is served only through a signed link that runs out (POST .../signed-url) and can be revoked. Choose private for anything holding personal data.", "type": "string" } }, "type": "object" } } }, "description": "Upload options", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_VISIBILITY", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_VISIBILITY` — visibility was neither \"public\" nor \"private\". No upload URL was made.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Start a direct upload. Returns upload_url — a single-use PUT target that expires in 300 seconds — and upload_id. PUT the file bytes to upload_url with no credentials (set Content-Type), then POST .../uploads/{upload_id}/commit.", "tags": [ "storage" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/storage/orgs/{org_id}/uploads/{id}/commit": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "UPLOAD_NOT_RECEIVED", "UPLOAD_EXPIRED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `UPLOAD_NOT_RECEIVED` — No file has arrived on the upload URL yet. Nothing was stored. PUT the file first, then commit.; `UPLOAD_EXPIRED` — The upload URL expired before any file arrived. Nothing was stored. Start again with POST /storage/orgs/{org_id}/uploads/begin.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Finish a direct upload. Reports what was stored: asset_id, bytes, sha256 of the received file, and the public url unless the upload was private. Safe to repeat — a second commit returns the same result.", "tags": [ "storage" ], "x-safety": { "denylist": false, "disclosure": "data_visible_publicly", "kind": "mutate", "reversible": false, "risk": "low" } } }, "/storage/uploads/{token}": { "put": { "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "UPLOAD_EXPIRED", "UPLOAD_ALREADY_USED", "FILE_TOO_LARGE", "UNSUPPORTED_TYPE" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `UPLOAD_EXPIRED` — This upload URL has expired. The file was NOT stored. Start again with POST /storage/orgs/{org_id}/uploads/begin.; `UPLOAD_ALREADY_USED` — This upload URL was already used. The file was NOT stored. Each URL works once.; `FILE_TOO_LARGE` — The upload is over the size cap for its detected type. The file was NOT stored.; `UNSUPPORTED_TYPE` — The content type could not be stored. The file was NOT stored." } }, "summary": "Single-use upload target. PUT the file bytes with Content-Type set; no credentials — the URL itself is the authorisation, works once, and expires 300 seconds after begin.", "tags": [ "storage" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/storage/{id}": { "get": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Expiry timestamp from a signed link. Set for you when the link is made; do not build one by hand.", "in": "query", "name": "exp", "required": false, "schema": { "type": "integer" } }, { "description": "Signature from a signed link. Set for you when the link is made.", "in": "query", "name": "sig", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "LINK_EXPIRED", "LINK_REVOKED", "SIGNING_UNAVAILABLE" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `LINK_EXPIRED` — The signed link ran out. The file was NOT sent. Ask the owner of the file for a new link.; `LINK_REVOKED` — The signed link was killed by the owner of the file. The file was NOT sent.; `SIGNING_UNAVAILABLE` — Private files cannot be served right now. The file was NOT sent and is safe." } }, "summary": "Serve a stored file. No credentials are needed for a public file, which is the default and means anyone holding the URL can read it forever. A private file needs a signed link (POST .../signed-url) and answers 404 without one.", "tags": [ "storage" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/t/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of t: method, path, auth, params, error codes — public, no auth", "tags": [ "t" ] } }, "/t/o": { "get": { "parameters": [ { "description": "Pixel id identifying the message whose open is being recorded.", "in": "query", "name": "pid", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "1x1 transparent open-pixel for email tracking (public).", "tags": [ "t" ] } }, "/t/p": { "get": { "parameters": [ { "description": "Pixel id to associate with the visitor.", "in": "query", "name": "pid", "required": false, "schema": { "type": "string" } }, { "description": "Page the visit is recorded against.", "in": "query", "name": "page", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Cookie-bridge pixel (cross-domain identity link).", "tags": [ "t" ] } }, "/tables/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of tables: method, path, auth, params, error codes — public, no auth", "tags": [ "tables" ] } }, "/tables/orgs/{org_id}/schema/dependents": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List everything pinned to a schema version (workflows, templates, meters) with its alignment against the active version.", "tags": [ "tables" ] } }, "/tables/orgs/{org_id}/schema/versions": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List schema versions, newest first, with which one is active.", "tags": [ "tables" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "definition": { "additionalProperties": true, "description": "{tables: {\u003cname\u003e: {columns: {\u003cname\u003e: {type, required?, default?, deprecated?, alias_of?, description?}}}}}. Types: text, number, integer, boolean, timestamp, json.", "type": "object" }, "note": { "description": "What changed in this version, for the humans reading the list.", "type": "string" } }, "required": [ "definition" ], "type": "object" } } }, "description": "The full schema document", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SCHEMA_INVALID", "SCHEMA_NOT_ADDITIVE", "SCHEMA_TOO_LARGE", "VERSION_LIMIT", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SCHEMA_INVALID` — The definition is malformed — the message names the table, column and fix. Nothing was created.; `SCHEMA_NOT_ADDITIVE` — The definition removes, retypes or tightens something — the message names it and the additive alternative. Nothing was created.; `SCHEMA_TOO_LARGE` — The definition is over 256 KB. Nothing was created.; `VERSION_LIMIT` — The org is at the version limit. Nothing was created — contact support.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create the next schema version. Send the WHOLE definition, not a delta. It is validated against the current latest under the append-only rules: nothing removed, nothing retyped, constraints only loosen — deprecate a column instead of deleting it. Version 1 activates itself; later versions wait for POST .../versions/{v}/activate.", "tags": [ "tables" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/tables/orgs/{org_id}/schema/versions/{v}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "v", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "VERSION_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `VERSION_NOT_FOUND` — No version with that number in this org.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Read one schema version: the full definition plus a diff against its parent (added tables/columns, deprecations).", "tags": [ "tables" ] } }, "/tables/orgs/{org_id}/schema/versions/{v}/activate": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "v", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "VERSION_NOT_FOUND", "PIN_BLOCKS_ACTIVATION", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `VERSION_NOT_FOUND` — No version with that number in this org.; `PIN_BLOCKS_ACTIVATION` — A dependent pins a newer version, so the activation was NOT performed. See GET /tables/orgs/{org_id}/schema/dependents and move the dependents first.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Make a version the active one. Rows validate against the active version. Activating an OLDER version is the undo path and is refused while any dependent pins a newer one.", "tags": [ "tables" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "POST /tables/orgs/{org_id}/schema/versions/{v}/activate", "reversible": true, "risk": "low" } } }, "/tables/orgs/{org_id}/{table}/rows": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "description": "Rows per page (1..200, default 50).", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Keyset cursor: a row id from the previous page; returns rows older than it.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "Pass true to include test rows.", "in": "query", "name": "include_test", "required": false, "schema": { "type": "boolean" } }, { "description": "Equality filter on a top-level field, e.g. filter[status]=paid. Repeatable across different columns.", "in": "query", "name": "filter[\u003ccolumn\u003e]", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_LIMIT", "INVALID_FILTER", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_LIMIT` — limit must be 1..200.; `INVALID_FILTER` — A filter names a field that is not a usable column name.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List rows, newest first. Test rows are excluded unless include_test=true.", "tags": [ "tables" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "doc": { "additionalProperties": true, "description": "The row as a JSON object; keys are column names in the table.", "type": "object" }, "test": { "description": "Store as a test row: flagged, excluded from default reads, never counted in reports. Default false.", "type": "boolean" } }, "required": [ "doc" ], "type": "object" } } }, "description": "The row", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "NO_ACTIVE_VERSION", "TABLE_NOT_FOUND", "ROW_INVALID", "ROW_TOO_LARGE", "ROW_CEILING_REACHED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `NO_ACTIVE_VERSION` — This org has no active schema version. Create one with POST /tables/orgs/{org_id}/schema/versions.; `TABLE_NOT_FOUND` — No table with that name in the active version.; `ROW_INVALID` — The row does not match the table — the message names the field and the fix. The row was NOT stored.; `ROW_TOO_LARGE` — The row is over 64 KB. The row was NOT stored — put large JSON in /database, files in /storage.; `ROW_CEILING_REACHED` — The org is at the 1,000,000-row beta ceiling. The row was NOT stored — contact support to raise it.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Insert a row. The row is validated against the active schema version: unknown fields, deprecated fields, type mismatches and missing required fields are refused with the exact field named; defaults fill in. Rows are 64 KB max. Set test: true to store a test row — excluded from default reads and reports. Emits a schema.row.inserted event.", "tags": [ "tables" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low", "test_mode": true } } }, "/tables/orgs/{org_id}/{table}/rows/{id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "ROW_NOT_FOUND", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `ROW_NOT_FOUND` — No row with that id in this table.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Read one row.", "tags": [ "tables" ] }, "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "doc": { "additionalProperties": true, "description": "Fields to set; null clears an optional field.", "type": "object" } }, "required": [ "doc" ], "type": "object" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "ROW_NOT_FOUND", "ROW_INVALID", "ROW_TOO_LARGE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `ROW_NOT_FOUND` — No row with that id in this table.; `ROW_INVALID` — The merged row does not match the table — the message names the field and the fix. The update was NOT applied.; `ROW_TOO_LARGE` — The merged row is over 64 KB. The update was NOT applied.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Partial update: sent fields replace, absent fields stay, null clears an optional field. The merged row is re-validated against the active version.", "tags": [ "tables" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/task/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of task: method, path, auth, params, error codes — public, no auth", "tags": [ "task" ] } }, "/task/orgs/{org_id}/tasks": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Tasks to return (1..100, default 20).", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Filter by task status.", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "description": "Filter by importance.", "in": "query", "name": "importance", "required": false, "schema": { "type": "string" } }, { "description": "Filter by assignee.", "in": "query", "name": "assignee", "required": false, "schema": { "type": "string" } }, { "description": "Filter by the source that created the task.", "in": "query", "name": "source", "required": false, "schema": { "type": "string" } }, { "description": "Filter by tag.", "in": "query", "name": "tag", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Ranked task list with queue-health meta", "properties": { "meta": { "description": "Queue health — distinct from the envelope meta", "properties": { "shown": { "description": "Rows returned", "type": "integer" }, "total_open": { "description": "Total open tasks in the org", "type": "integer" } }, "type": "object" }, "tasks": { "description": "Ranked task rows (thin projection)", "items": { "description": "A ranked task list row", "properties": { "description": { "description": "Triage key", "type": "string" }, "id": { "description": "Task id", "type": "string" }, "score": { "description": "Derived rank", "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List tasks — the agent-loop hot path. Default: top 20 open tasks ranked by score, projected to {id, description, score}. data.meta carries queue health {shown, total_open}.", "tags": [ "task" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "assignee": { "description": "Optional email. An assigned task emails the assignee a one-click magic-link to resolve it.", "type": "string" }, "body": { "description": "Full Markdown context. Staged to the body tier; read once via task get, never on the list hot path.", "type": "string" }, "dedup_key": { "description": "Optional idempotency key; a repeated key returns the existing task.", "type": "string" }, "depends_on": { "description": "Task ids this task waits on. Immutable — declared only at creation, which makes the graph a DAG by construction.", "items": { "description": "A task id", "type": "string" }, "type": "array" }, "description": { "description": "Triage key — ~100 tokens, exactly enough to decide whether to pick this before that. Not a summary.", "type": "string" }, "due_at": { "description": "Optional RFC3339 deadline; feeds urgency in the ranking.", "type": "string" }, "importance": { "description": "Drives ranking. Set by the promoter at creation.", "enum": [ "low", "normal", "high", "critical" ], "type": "string" }, "resolve_on": { "additionalProperties": true, "description": "Optional event matcher {event_type, field, value}; a matching event auto-resolves the task.", "type": "object" }, "source": { "description": "Which service/agent/workflow created the task. Default 'manual'.", "type": "string" }, "tags": { "description": "Free-form labels that partition the queue (e.g. support, sales).", "items": { "description": "A tag", "type": "string" }, "type": "array" } }, "required": [ "description" ], "type": "object" } } }, "description": "Task creation payload", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A task", "properties": { "assignee": { "description": "Assignee email (omitted when unset)", "type": "string" }, "claimed_by": { "description": "Current lease holder (omitted when unset)", "type": "string" }, "created_at": { "description": "RFC3339 creation time", "type": "string" }, "dedup_key": { "description": "Idempotency key (omitted when unset)", "type": "string" }, "depends_on": { "description": "Task ids this task waits on", "items": { "description": "A task id", "type": "string" }, "type": "array" }, "description": { "description": "Triage key", "type": "string" }, "due_at": { "description": "RFC3339 deadline (omitted when unset)", "type": "string" }, "fail_reason": { "description": "Why the task failed (omitted when unset)", "type": "string" }, "id": { "description": "Task id", "type": "string" }, "importance": { "description": "Importance tier", "enum": [ "low", "normal", "high", "critical" ], "type": "string" }, "lease_expires_at": { "description": "RFC3339 claim-lease expiry (omitted when unset)", "type": "string" }, "org_id": { "description": "Owning org id", "type": "string" }, "payload_url": { "description": "URL of the task-body endpoint", "type": "string" }, "resolve_on": { "additionalProperties": true, "description": "Event matcher that auto-resolves the task (omitted when unset)", "type": "object" }, "resolved_at": { "description": "RFC3339 resolution time (omitted when unset)", "type": "string" }, "score": { "description": "Derived rank (importance + urgency)", "type": "integer" }, "source": { "description": "Which service/agent/workflow created the task", "type": "string" }, "status": { "description": "Lifecycle state", "enum": [ "open", "claimed", "blocked", "resolved", "failed", "cancelled" ], "type": "string" }, "tags": { "description": "Free-form partition labels", "items": { "description": "A tag", "type": "string" }, "type": "array" }, "updated_at": { "description": "RFC3339 last-update time", "type": "string" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a task. The Markdown body is accepted inline and staged out-of-band. Idempotent on (org_id, dedup_key) — a repeated key returns the existing task at 200 instead of 201. A task with unresolved depends_on starts blocked; one with an assignee emails them a magic-link.", "tags": [ "task" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /task/orgs/{org_id}/tasks/{id}", "reversible": true, "risk": "low" } } }, "/task/orgs/{org_id}/tasks/{id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success — no content" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Cancel a task (terminal, distinct from fail).", "tags": [ "task" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } }, "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A task", "properties": { "assignee": { "description": "Assignee email (omitted when unset)", "type": "string" }, "claimed_by": { "description": "Current lease holder (omitted when unset)", "type": "string" }, "created_at": { "description": "RFC3339 creation time", "type": "string" }, "dedup_key": { "description": "Idempotency key (omitted when unset)", "type": "string" }, "depends_on": { "description": "Task ids this task waits on", "items": { "description": "A task id", "type": "string" }, "type": "array" }, "description": { "description": "Triage key", "type": "string" }, "due_at": { "description": "RFC3339 deadline (omitted when unset)", "type": "string" }, "fail_reason": { "description": "Why the task failed (omitted when unset)", "type": "string" }, "id": { "description": "Task id", "type": "string" }, "importance": { "description": "Importance tier", "enum": [ "low", "normal", "high", "critical" ], "type": "string" }, "lease_expires_at": { "description": "RFC3339 claim-lease expiry (omitted when unset)", "type": "string" }, "org_id": { "description": "Owning org id", "type": "string" }, "payload_url": { "description": "URL of the task-body endpoint", "type": "string" }, "resolve_on": { "additionalProperties": true, "description": "Event matcher that auto-resolves the task (omitted when unset)", "type": "object" }, "resolved_at": { "description": "RFC3339 resolution time (omitted when unset)", "type": "string" }, "score": { "description": "Derived rank (importance + urgency)", "type": "integer" }, "source": { "description": "Which service/agent/workflow created the task", "type": "string" }, "status": { "description": "Lifecycle state", "enum": [ "open", "claimed", "blocked", "resolved", "failed", "cancelled" ], "type": "string" }, "tags": { "description": "Free-form partition labels", "items": { "description": "A tag", "type": "string" }, "type": "array" }, "updated_at": { "description": "RFC3339 last-update time", "type": "string" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get the full task object.", "tags": [ "task" ] } }, "/task/orgs/{org_id}/tasks/{id}/body": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A task's Markdown body", "properties": { "body": { "description": "The Markdown body", "type": "string" }, "task_id": { "description": "Task id", "type": "string" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get the task's Markdown body (the body tier). Read once, when an agent commits to a task.", "tags": [ "task" ] } }, "/task/orgs/{org_id}/tasks/{id}/claim": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lease_seconds": { "description": "Lease length in seconds (default 600, max 86400).", "type": "integer" }, "worker": { "description": "Optional claimer id; defaults to the API key id.", "type": "string" } }, "type": "object" } } }, "description": "Claim payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A task", "properties": { "assignee": { "description": "Assignee email (omitted when unset)", "type": "string" }, "claimed_by": { "description": "Current lease holder (omitted when unset)", "type": "string" }, "created_at": { "description": "RFC3339 creation time", "type": "string" }, "dedup_key": { "description": "Idempotency key (omitted when unset)", "type": "string" }, "depends_on": { "description": "Task ids this task waits on", "items": { "description": "A task id", "type": "string" }, "type": "array" }, "description": { "description": "Triage key", "type": "string" }, "due_at": { "description": "RFC3339 deadline (omitted when unset)", "type": "string" }, "fail_reason": { "description": "Why the task failed (omitted when unset)", "type": "string" }, "id": { "description": "Task id", "type": "string" }, "importance": { "description": "Importance tier", "enum": [ "low", "normal", "high", "critical" ], "type": "string" }, "lease_expires_at": { "description": "RFC3339 claim-lease expiry (omitted when unset)", "type": "string" }, "org_id": { "description": "Owning org id", "type": "string" }, "payload_url": { "description": "URL of the task-body endpoint", "type": "string" }, "resolve_on": { "additionalProperties": true, "description": "Event matcher that auto-resolves the task (omitted when unset)", "type": "object" }, "resolved_at": { "description": "RFC3339 resolution time (omitted when unset)", "type": "string" }, "score": { "description": "Derived rank (importance + urgency)", "type": "integer" }, "source": { "description": "Which service/agent/workflow created the task", "type": "string" }, "status": { "description": "Lifecycle state", "enum": [ "open", "claimed", "blocked", "resolved", "failed", "cancelled" ], "type": "string" }, "tags": { "description": "Free-form partition labels", "items": { "description": "A tag", "type": "string" }, "type": "array" }, "updated_at": { "description": "RFC3339 last-update time", "type": "string" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Claim a task — an atomic lease (default 10 min). Lease expiry auto-reverts the task to open.", "tags": [ "task" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/task/orgs/{org_id}/tasks/{id}/extend": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lease_seconds": { "description": "New lease length from now (default 600, max 86400).", "type": "integer" } }, "type": "object" } } }, "description": "Extend payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A task", "properties": { "assignee": { "description": "Assignee email (omitted when unset)", "type": "string" }, "claimed_by": { "description": "Current lease holder (omitted when unset)", "type": "string" }, "created_at": { "description": "RFC3339 creation time", "type": "string" }, "dedup_key": { "description": "Idempotency key (omitted when unset)", "type": "string" }, "depends_on": { "description": "Task ids this task waits on", "items": { "description": "A task id", "type": "string" }, "type": "array" }, "description": { "description": "Triage key", "type": "string" }, "due_at": { "description": "RFC3339 deadline (omitted when unset)", "type": "string" }, "fail_reason": { "description": "Why the task failed (omitted when unset)", "type": "string" }, "id": { "description": "Task id", "type": "string" }, "importance": { "description": "Importance tier", "enum": [ "low", "normal", "high", "critical" ], "type": "string" }, "lease_expires_at": { "description": "RFC3339 claim-lease expiry (omitted when unset)", "type": "string" }, "org_id": { "description": "Owning org id", "type": "string" }, "payload_url": { "description": "URL of the task-body endpoint", "type": "string" }, "resolve_on": { "additionalProperties": true, "description": "Event matcher that auto-resolves the task (omitted when unset)", "type": "object" }, "resolved_at": { "description": "RFC3339 resolution time (omitted when unset)", "type": "string" }, "score": { "description": "Derived rank (importance + urgency)", "type": "integer" }, "source": { "description": "Which service/agent/workflow created the task", "type": "string" }, "status": { "description": "Lifecycle state", "enum": [ "open", "claimed", "blocked", "resolved", "failed", "cancelled" ], "type": "string" }, "tags": { "description": "Free-form partition labels", "items": { "description": "A tag", "type": "string" }, "type": "array" }, "updated_at": { "description": "RFC3339 last-update time", "type": "string" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Extend a live claim — a heartbeat for long work.", "tags": [ "task" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/task/orgs/{org_id}/tasks/{id}/fail": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Why the task failed.", "type": "string" } }, "type": "object" } } }, "description": "Fail payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A task", "properties": { "assignee": { "description": "Assignee email (omitted when unset)", "type": "string" }, "claimed_by": { "description": "Current lease holder (omitted when unset)", "type": "string" }, "created_at": { "description": "RFC3339 creation time", "type": "string" }, "dedup_key": { "description": "Idempotency key (omitted when unset)", "type": "string" }, "depends_on": { "description": "Task ids this task waits on", "items": { "description": "A task id", "type": "string" }, "type": "array" }, "description": { "description": "Triage key", "type": "string" }, "due_at": { "description": "RFC3339 deadline (omitted when unset)", "type": "string" }, "fail_reason": { "description": "Why the task failed (omitted when unset)", "type": "string" }, "id": { "description": "Task id", "type": "string" }, "importance": { "description": "Importance tier", "enum": [ "low", "normal", "high", "critical" ], "type": "string" }, "lease_expires_at": { "description": "RFC3339 claim-lease expiry (omitted when unset)", "type": "string" }, "org_id": { "description": "Owning org id", "type": "string" }, "payload_url": { "description": "URL of the task-body endpoint", "type": "string" }, "resolve_on": { "additionalProperties": true, "description": "Event matcher that auto-resolves the task (omitted when unset)", "type": "object" }, "resolved_at": { "description": "RFC3339 resolution time (omitted when unset)", "type": "string" }, "score": { "description": "Derived rank (importance + urgency)", "type": "integer" }, "source": { "description": "Which service/agent/workflow created the task", "type": "string" }, "status": { "description": "Lifecycle state", "enum": [ "open", "claimed", "blocked", "resolved", "failed", "cancelled" ], "type": "string" }, "tags": { "description": "Free-form partition labels", "items": { "description": "A tag", "type": "string" }, "type": "array" }, "updated_at": { "description": "RFC3339 last-update time", "type": "string" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Fail a task (terminal, with a reason). Returns the updated task. Does not auto-retry — re-filing is explicit. Cascades: dependents that can never proceed are auto-failed.", "tags": [ "task" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/task/orgs/{org_id}/tasks/{id}/resolve": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Why the task was resolved — stored on the timeline", "type": "string" } }, "type": "object" } } }, "description": "Resolution note", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A task", "properties": { "assignee": { "description": "Assignee email (omitted when unset)", "type": "string" }, "claimed_by": { "description": "Current lease holder (omitted when unset)", "type": "string" }, "created_at": { "description": "RFC3339 creation time", "type": "string" }, "dedup_key": { "description": "Idempotency key (omitted when unset)", "type": "string" }, "depends_on": { "description": "Task ids this task waits on", "items": { "description": "A task id", "type": "string" }, "type": "array" }, "description": { "description": "Triage key", "type": "string" }, "due_at": { "description": "RFC3339 deadline (omitted when unset)", "type": "string" }, "fail_reason": { "description": "Why the task failed (omitted when unset)", "type": "string" }, "id": { "description": "Task id", "type": "string" }, "importance": { "description": "Importance tier", "enum": [ "low", "normal", "high", "critical" ], "type": "string" }, "lease_expires_at": { "description": "RFC3339 claim-lease expiry (omitted when unset)", "type": "string" }, "org_id": { "description": "Owning org id", "type": "string" }, "payload_url": { "description": "URL of the task-body endpoint", "type": "string" }, "resolve_on": { "additionalProperties": true, "description": "Event matcher that auto-resolves the task (omitted when unset)", "type": "object" }, "resolved_at": { "description": "RFC3339 resolution time (omitted when unset)", "type": "string" }, "score": { "description": "Derived rank (importance + urgency)", "type": "integer" }, "source": { "description": "Which service/agent/workflow created the task", "type": "string" }, "status": { "description": "Lifecycle state", "enum": [ "open", "claimed", "blocked", "resolved", "failed", "cancelled" ], "type": "string" }, "tags": { "description": "Free-form partition labels", "items": { "description": "A tag", "type": "string" }, "type": "array" }, "updated_at": { "description": "RFC3339 last-update time", "type": "string" } }, "type": "object" }, "error": { "nullable": true }, "meta": { "properties": { "latency_ms": { "type": "integer" }, "request_id": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "success": { "enum": [ true ], "type": "boolean" } }, "required": [ "success", "data", "meta" ], "type": "object" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Resolve a task (terminal). Returns the updated task. Unblocks any tasks that depended on it.", "tags": [ "task" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/url/go/{code}": { "get": { "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Public attributed redirect: 302 to the link's target with ?src= appended, click logged. No auth — this is the URL that gets shared.", "tags": [ "url" ] } }, "/url/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of url: method, path, auth, params, error codes — public, no auth", "tags": [ "url" ] } }, "/url/orgs/{org_id}/content-report": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Only this piece's rows.", "in": "query", "name": "piece_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "The content-distribution scoreboard: attributed signups per piece per channel, from the first-touch cookie captured at account creation. This is THE metric — clicks (GET .../links) are diagnostic, activations are the tiebreaker between channels. Filter with ?piece_id=.", "tags": [ "url" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } } }, "/url/orgs/{org_id}/links": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Only links for this piece.", "in": "query", "name": "piece_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List attributed links with their click counts: human_clicks, bot_clicks (conservative user-agent verdict recorded at click time) and human_visitors (distinct by hashed ip+ua). Filter with ?piece_id=. Raw clicks flatter a piece — human_visitors is the diagnostic number; signups are the scoreboard.", "tags": [ "url" ], "x-safety": { "denylist": false, "kind": "read", "reversible": true, "risk": "low" } }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "piece_id": { "description": "Stable id of the content piece this link promotes.", "type": "string" }, "src": { "description": "Channel tag appended to the target as ?src=, e.g. x, linkedin, email.", "type": "string" }, "target": { "description": "Absolute http(s) URL the link redirects to.", "type": "string" } }, "required": [ "target", "piece_id", "src" ], "type": "object" } } }, "description": "Attributed link", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_TARGET", "INVALID_ATTRIBUTION", "INVALID_JSON", "RATE_LIMITED", "INVALID_REQUEST", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_TARGET` — target must be an absolute http or https URL, up to 2048 characters.; `INVALID_ATTRIBUTION` — piece_id and src are required: letters, digits, dot, dash, underscore, up to 80 characters.; `INVALID_JSON` — The request body is not valid JSON.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create an attributed short link. The redirect appends ?src=\u003csrc\u003e to the target and logs the click with a bot/human verdict, so downstream attribution only reasons about src and referrer. Use one link per piece × channel.", "tags": [ "url" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/url/orgs/{org_id}/shorten": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "url": { "description": "Long URL to shorten; scheme auto-prepended if missing", "type": "string" } }, "required": [ "url" ], "type": "object" } } }, "description": "Shorten payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "SHORTENER_NOT_CONFIGURED", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `SHORTENER_NOT_CONFIGURED` — This deployment has no edge resolver, so a short link could not resolve. The link was NOT created.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a short link for the org", "tags": [ "url" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/v1/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of v1: method, path, auth, params, error codes — public, no auth", "tags": [ "v1" ] } }, "/v1/integrations/skills-install": { "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "agents_targeted": { "description": "Which agent dirs were touched by the install", "items": { "description": "", "enum": [ "claude", "gemini", "cursor" ], "type": "string" }, "type": "array" }, "cli_version": { "description": "Semver of the CLI that emitted the event", "type": "string" } }, "required": [ "cli_version" ], "type": "object" } } }, "description": "skills.install event payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Telemetry — skills.install event from the integrations CLI (S-205)", "tags": [ "v1" ] } }, "/webhook/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of webhook: method, path, auth, params, error codes — public, no auth", "tags": [ "webhook" ] } }, "/webhook/in/{slug}": { "post": { "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "WORKFLOW_DEPTH_EXCEEDED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `WORKFLOW_DEPTH_EXCEEDED` — The delivery was refused: the workflow chain is too deep. Remove the loop." } }, "summary": "Public webhook receiver (auth-free; payload stored)", "tags": [ "webhook" ] } }, "/webhook/orgs/{org_id}/deliveries": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Deliveries per page (1..200, default 50). Out-of-range values are rejected with 400 rather than clamped.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Keyset cursor — pass the previous page's meta.next_cursor. Absent on the last page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Filter to one endpoint. An id belonging to another org returns 404, not an empty page.", "in": "query", "name": "endpoint_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List received webhook deliveries, newest first. Keyset-paginated: pass the previous page's meta.next_cursor as ?cursor=. Optional ?endpoint_id= filters to one endpoint. This is how an agent reads its own form submissions — the delivery_id returned by POST /webhook/in/{slug} goes to whoever POSTed (for a funnel form, the visitor's browser), so it is not available to the org that owns the form.", "tags": [ "webhook" ] } }, "/webhook/orgs/{org_id}/deliveries/{id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single webhook delivery (payload + meta)", "tags": [ "webhook" ] } }, "/webhook/orgs/{org_id}/endpoints": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List webhook endpoints for the org", "tags": [ "webhook" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "crm_email_path": { "description": "Dot-path to the contact email field in inbound JSON bodies. Default \"email\". Empty disables CRM auto-ingest.", "type": "string" }, "description": { "description": "What this endpoint receives", "type": "string" }, "forward_url": { "description": "Optional URL to forward each inbound delivery to (POST, async, best-effort). Use http:// or https://. Empty = no forwarding.", "type": "string" }, "name": { "description": "Display name (e.g. \"order-notifications\")", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "description": "Webhook endpoint creation payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a public webhook endpoint (returns slug). Optional crm_email_path enables auto-ingest of the contact email into CRM via a dot-path (default \"email\" = top-level; e.g. \"data.object.customer_email\" for Stripe, \"sender.email\" for GitHub). Pass empty string to disable CRM ingest for this endpoint. Optional forward_url, when set, causes every inbound delivery to be POSTed (async, best-effort) to that URL with X-MyAPI-Webhook-{Endpoint,Delivery}-Id headers attached.", "tags": [ "webhook" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /webhook/orgs/{org_id}/endpoints/{id}", "reversible": true, "risk": "low" } } }, "/webhook/orgs/{org_id}/endpoints/{id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete a webhook endpoint", "tags": [ "webhook" ], "x-safety": { "denylist": false, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } }, "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "crm_email_path": { "description": "Dot-path to the contact email field in inbound JSON bodies. Empty disables CRM auto-ingest.", "type": "string" }, "description": { "description": "What this endpoint receives", "type": "string" }, "forward_url": { "description": "URL to forward each inbound delivery to. Empty string clears the forward.", "type": "string" }, "name": { "description": "Display name", "type": "string" } }, "type": "object" } } }, "description": "Webhook endpoint update payload (all fields optional)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Update a webhook endpoint. Mutable fields: name, description, crm_email_path, forward_url. Slug is immutable.", "tags": [ "webhook" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/workflow/help": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Client error" } }, "summary": "Every endpoint of workflow: method, path, auth, params, error codes — public, no auth", "tags": [ "workflow" ] } }, "/workflow/orgs/{org_id}/runs/{id}": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single workflow run", "tags": [ "workflow" ] } }, "/workflow/orgs/{org_id}/workflows": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List workflows for the org", "tags": [ "workflow" ] }, "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "Display name", "type": "string" }, "steps": { "description": "Ordered list of steps; each step has a `type` (\"email\" | \"slack\")", "items": { "type": "object" }, "type": "array" }, "trigger_config": { "additionalProperties": true, "description": "What fires this workflow. For webhook: endpoint_id (a webhook endpoint id) or webhook_slug (resolved and stored as endpoint_id). For schema.row.inserted: {\"table\": \"\u003cname\u003e\"} — a table in the active schema version; the workflow is pinned to that version and steps read the row via {{payload.doc.\u003ccolumn\u003e}}. For cron: {\"schedule\": \"m h dom mon dow\"} in UTC (five numeric fields; *, lists, ranges, steps) — the payload is {trigger, schedule, at}", "type": "object" }, "trigger_type": { "description": "What kind of event fires this workflow (default webhook)", "enum": [ "webhook", "schema.row.inserted", "cron" ], "type": "string" } }, "required": [ "name", "steps" ], "type": "object" } } }, "description": "Workflow creation payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "STEPS_REQUIRED", "INVALID_STEP_TYPE", "INVALID_TRIGGER_TYPE", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `STEPS_REQUIRED` — Send at least one step. Nothing was created.; `INVALID_STEP_TYPE` — A step has an unknown type — see the message. Nothing was created.; `INVALID_TRIGGER_TYPE` — trigger_type must be webhook, schema.row.inserted or cron. Nothing was created.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Create a workflow (trigger + steps)", "tags": [ "workflow" ], "x-safety": { "denylist": false, "kind": "mutate", "reverse": "DELETE /workflow/orgs/{org_id}/workflows/{id}", "reversible": true, "risk": "low" } } }, "/workflow/orgs/{org_id}/workflows/{id}": { "delete": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Delete a workflow", "tags": [ "workflow" ], "x-safety": { "denylist": false, "disclosure": "not_undoable", "kind": "mutate", "reversible": false, "risk": "high" } }, "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Get a single workflow", "tags": [ "workflow" ] }, "patch": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "Workflow name", "type": "string" }, "steps": { "description": "Ordered actions to run", "items": { "additionalProperties": true, "description": "A single workflow step", "type": "object" }, "type": "array" }, "trigger_config": { "additionalProperties": true, "description": "What fires this workflow. Pass endpoint_id (a webhook endpoint id), or webhook_slug (the endpoint's slug — resolved and stored as endpoint_id)", "type": "object" } }, "type": "object" } } }, "description": "Fields to change — omitted fields are left untouched", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "INVALID_STEP_TYPE", "NAME_CANNOT_BE_EMPTY", "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `INVALID_STEP_TYPE` — A step has an unknown type — see the message. Nothing was changed.; `NAME_CANNOT_BE_EMPTY` — name cannot be set to an empty string.; `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Update a workflow", "tags": [ "workflow" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/workflow/orgs/{org_id}/workflows/{id}/disable": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Disable a workflow", "tags": [ "workflow" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/workflow/orgs/{org_id}/workflows/{id}/enable": { "post": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Enable a workflow (start consuming triggers)", "tags": [ "workflow" ], "x-safety": { "denylist": false, "kind": "mutate", "reversible": false, "risk": "low" } } }, "/workflow/orgs/{org_id}/workflows/{id}/runs": { "get": { "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Runs per page (1..500, default 100). Out-of-range values are rejected with 400.", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Keyset cursor from the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "List workflow runs, newest first.", "tags": [ "workflow" ] } }, "/{domain}/{code}": { "get": { "parameters": [ { "in": "path", "name": "domain", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } }, "description": "Success — JSON envelope" }, "4XX": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "enum": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_JSON", "BODY_TOO_LARGE", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "INTERNAL_ERROR", "UPSTREAM_ERROR", "UNAVAILABLE", "INSUFFICIENT_FUNDS", "SPEND_CAP_EXCEEDED", "FREE_TIER_EXHAUSTED", "ORG_ARCHIVED" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Client error. Codes: `RATE_LIMITED` — Too many requests. Retry after the interval in the Retry-After header.; `INVALID_REQUEST` — The request shape is wrong. The message names the field or value to fix.; `INVALID_JSON` — The request body is not valid JSON. Fix the body and send it again.; `BODY_TOO_LARGE` — The request body is over this route's size cap. Nothing was saved; the message states the limit in bytes.; `UNAUTHORIZED` — The caller is not authenticated. Send a valid API key in the Authorization header.; `FORBIDDEN` — The credential cannot use this resource. Use a key with the right org and grants.; `NOT_FOUND` — The resource does not exist for this org. The message names what was looked up.; `CONFLICT` — The resource is in a state that refuses this change. The message names the conflict.; `PAYLOAD_TOO_LARGE` — The request body is over the size cap. Send a smaller payload.; `INTERNAL_ERROR` — The operation failed on our side and was NOT completed. Retry, or contact support.; `UPSTREAM_ERROR` — A dependency of this operation failed. The operation was NOT completed; retry.; `UNAVAILABLE` — This capability is not available right now. Retry later.; `INSUFFICIENT_FUNDS` — The account balance cannot cover this call. Add funds via POST /hq/billing/topup, or turn on auto-recharge. Nothing was charged and the call did NOT run. Every 402 body carries `code`, a `message` naming the fix endpoint, an optional `cli_hint` naming a second way to do the same fix when one exists, and here an `auto_recharge` state (in_flight | disabled | capped | no_pm | failed) plus `retry_after_seconds` when a refill is in flight.; `SPEND_CAP_EXCEEDED` — A spend cap is reached — `scope` says which: account (raise it via PATCH /hq/account/spend-cap) or key (mint a key with a higher spend_cap_cents via POST /hq/account/create/key). The call did NOT run. The body carries cap_cents, spent_cents and period.; `FREE_TIER_EXHAUSTED` — The free-tier allowance for this primitive is used up. Add funds via POST /hq/billing/topup to continue; GET /hq/account/free-tier shows what remains.; `ORG_ARCHIVED` — The organisation named in the path is archived and accepts no changes. Reads still work. Nothing was performed. Reopen it with POST /hq/orgs/{id}/unarchive." } }, "summary": "Public URL-shortener redirect", "tags": [ "root" ] } } }, "servers": [ { "url": "https://api.myapihq.com" } ], "tags": [ { "name": ".well-known" }, { "name": "admin" }, { "name": "audience" }, { "name": "auth" }, { "name": "billing" }, { "name": "comments" }, { "name": "company" }, { "name": "console" }, { "name": "container" }, { "name": "crm" }, { "name": "database" }, { "name": "domain" }, { "name": "email" }, { "name": "events" }, { "name": "feedback" }, { "name": "function" }, { "name": "funnel" }, { "name": "git" }, { "name": "goal" }, { "name": "help" }, { "name": "hq" }, { "name": "image" }, { "name": "kms" }, { "name": "launch" }, { "name": "llm" }, { "name": "mcp" }, { "name": "offer" }, { "name": "ops" }, { "name": "outcome" }, { "name": "outreach" }, { "name": "payments" }, { "name": "people" }, { "name": "pixel" }, { "name": "queue" }, { "name": "referral" }, { "name": "root" }, { "name": "runner" }, { "name": "runs" }, { "name": "schema" }, { "name": "storage" }, { "name": "t" }, { "name": "tables" }, { "name": "task" }, { "name": "url" }, { "name": "v1" }, { "name": "webhook" }, { "name": "workflow" } ] }