{"openapi":"3.1.0","info":{"title":"Relay Agent Tool API","version":"2026-08-09","description":"Metered, agent-native tool API. Agents authenticate with a workspace API key and pay per call in credits."},"servers":[{"url":"https://3bi.ai"}],"components":{"securitySchemes":{"agentKey":{"type":"http","scheme":"bearer","bearerFormat":"sk_agent_..."}}},"paths":{"/api/public/v1/tools/fetch_url":{"post":{"operationId":"fetch_url","summary":"Fetch URL","description":"Fetch a public web page or JSON endpoint over HTTPS and return its readable text content plus metadata. Real network call, not a simulation. Read-only. Costs 2 credit(s).","security":[{"agentKey":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Replay-safe key scoped to your API key. A repeated completed call returns the stored response and is not charged again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Absolute https:// URL to fetch"},"maxChars":{"type":"number","description":"Truncate the extracted text to this many characters (default 8000, max 50000)"}},"required":["url"],"additionalProperties":false},"examples":{"default":{"summary":"Example call","value":{"url":"https://example.com"}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"examples":{"default":{"summary":"Success","value":{"ok":true,"requestId":"b0e1c8a2-9f4d-4d0f-9a1e-2c5d7f8e1a30","tool":"fetch_url","demo":false,"credits":{"charged":2,"balance":498},"result":{"ok":true,"url":"https://example.com/","status":200,"contentType":"text/html","title":"Example Domain","text":"Example Domain. This domain is for use in illustrative examples in documents...","chars":208,"truncated":false,"fetchedAt":"2026-08-09T20:15:18.358Z"}}}}}}},"401":{"description":"missing_api_key: No Authorization: Bearer header on the request. → Send Authorization: Bearer sk_agent_… , or POST /api/public/v1/signup to mint a key.\ninvalid_api_key: The key is unknown, revoked, or past its rotation grace window. → Rotate with POST /api/public/v1/keys/rotate, or create a new key in the console.\nkey_expired: The key passed the expiry date set by its owner. → Rotate the key or issue a new one in the console.","content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"ok":false,"error":{"code":"missing_api_key","message":"No Authorization: Bearer header on the request."}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"ok":false,"error":{"code":"invalid_api_key","message":"The key is unknown, revoked, or past its rotation grace window."}}},"key_expired":{"summary":"key_expired","value":{"ok":false,"error":{"code":"key_expired","message":"The key passed the expiry date set by its owner."}}}}}}},"402":{"description":"insufficient_credits: The workspace balance is below this tool's price. Nothing was executed or charged. → Pay machine-to-machine: the body carries an x402 accepts[] offer — settle it and retry the same request with an X-PAYMENT header. Humans can instead buy credits via POST /api/public/v1/claim.\npayment_failed: An X-PAYMENT header was supplied but the facilitator could not verify or settle it. → Re-read accepts[0] from a fresh 402, rebuild the payment payload for the exact amount, asset and network, and retry.","content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"ok":false,"error":{"code":"insufficient_credits","message":"The workspace balance is below this tool's price. Nothing was executed or charged.","required":5,"balance":2}}},"payment_failed":{"summary":"payment_failed","value":{"ok":false,"error":{"code":"payment_failed","message":"An X-PAYMENT header was supplied but the facilitator could not verify or settle it."}}}}}}},"403":{"description":"budget_exceeded: The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key. → Wait for the window to roll over, or ask the key owner to raise the cap in the console.\ntool_not_allowed: This key has a tool allowlist that does not include the requested tool. → Call an allowed tool, or ask the key owner to widen the allowlist.\ntool_disabled: The workspace owner has disabled this tool for the org. → Enable the tool in the console, or call a different tool.\ninsufficient_scope: The key is valid but does not carry the tools:invoke scope. → Issue a key with tools:invoke from the console and retry with it.","content":{"application/json":{"examples":{"budget_exceeded":{"summary":"budget_exceeded","value":{"ok":false,"error":{"code":"budget_exceeded","message":"The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key."}}},"tool_not_allowed":{"summary":"tool_not_allowed","value":{"ok":false,"error":{"code":"tool_not_allowed","message":"This key has a tool allowlist that does not include the requested tool."}}},"tool_disabled":{"summary":"tool_disabled","value":{"ok":false,"error":{"code":"tool_disabled","message":"The workspace owner has disabled this tool for the org."}}},"insufficient_scope":{"summary":"insufficient_scope","value":{"ok":false,"error":{"code":"insufficient_scope","message":"The key is valid but does not carry the tools:invoke scope."}}}}}}},"404":{"description":"unknown_tool: No public tool with that name exists in the catalog. → Re-read GET /api/public/v1/tools and use an exact name from the catalog.\napproval_intent_not_found: No approval intent with that id exists in this workspace. → Use the intent_id from the 428 approval object; intents expire after 24 hours.\noauth_provider_unknown: No OAuth provider with that slug is enabled. → GET /api/public/v1/oauth/providers for the supported catalog.\nconnection_not_found: No OAuth connection with that id exists in this workspace. → List connections with GET /api/public/v1/oauth/connections and use a current id.","content":{"application/json":{"examples":{"unknown_tool":{"summary":"unknown_tool","value":{"ok":false,"error":{"code":"unknown_tool","message":"No public tool with that name exists in the catalog."}}},"approval_intent_not_found":{"summary":"approval_intent_not_found","value":{"ok":false,"error":{"code":"approval_intent_not_found","message":"No approval intent with that id exists in this workspace."}}},"oauth_provider_unknown":{"summary":"oauth_provider_unknown","value":{"ok":false,"error":{"code":"oauth_provider_unknown","message":"No OAuth provider with that slug is enabled."}}},"connection_not_found":{"summary":"connection_not_found","value":{"ok":false,"error":{"code":"connection_not_found","message":"No OAuth connection with that id exists in this workspace."}}}}}}},"409":{"description":"request_in_progress: Another call with the same idempotency-key is still executing, or an approved confirmation token is already running. → Wait and retry the same idempotency-key to receive the stored response; do not change the body. If the original request is known to have failed, retry with a new idempotency-key. For a confirmation token, call the tool again with no token to get a fresh preview.\noauth_connection_required: This tool needs a connected third-party account, and none is linked for this workspace. → POST the connect URL from the body with your API key to get an authorization URL, have your operator complete the OAuth flow, then retry the call.","content":{"application/json":{"examples":{"request_in_progress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"Another call with the same idempotency-key is still executing, or an approved confirmation token is already running."}}},"oauth_connection_required":{"summary":"oauth_connection_required","value":{"ok":false,"error":{"code":"oauth_connection_required","message":"This tool needs a connected third-party account, and none is linked for this workspace."}}}}}}},"422":{"description":"invalid_json: The request body was not valid JSON. → Send a JSON object with content-type: application/json.\ninvalid_input: Arguments failed the tool's JSON Schema. No credits were charged. → Fix the fields listed in error.issues[].path and resend.","content":{"application/json":{"examples":{"invalid_json":{"summary":"invalid_json","value":{"ok":false,"error":{"code":"invalid_json","message":"The request body was not valid JSON."}}},"invalid_input":{"summary":"invalid_input","value":{"ok":false,"error":{"code":"invalid_input","message":"Arguments failed the tool's JSON Schema. No credits were charged."}}}}}}},"429":{"description":"rate_limited: Over 60 calls per minute for this API key. → Back off ~1 minute, or mint additional keys for parallel workers.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Over 60 calls per minute for this API key."}}}}}}},"500":{"description":"oauth_authorize_failed: The OAuth authorization URL could not be generated. → Retry; if it persists, check that the provider is still enabled.\ncatalog_unavailable: The OAuth provider catalog could not be loaded. → Retry shortly.\nconnections_unavailable: The workspace's OAuth connections could not be listed. → Retry shortly.\nrevoke_failed: The OAuth connection could not be revoked. → Retry; the connection remains active until revocation succeeds.","content":{"application/json":{"examples":{"oauth_authorize_failed":{"summary":"oauth_authorize_failed","value":{"ok":false,"error":{"code":"oauth_authorize_failed","message":"The OAuth authorization URL could not be generated."}}},"catalog_unavailable":{"summary":"catalog_unavailable","value":{"ok":false,"error":{"code":"catalog_unavailable","message":"The OAuth provider catalog could not be loaded."}}},"connections_unavailable":{"summary":"connections_unavailable","value":{"ok":false,"error":{"code":"connections_unavailable","message":"The workspace's OAuth connections could not be listed."}}},"revoke_failed":{"summary":"revoke_failed","value":{"ok":false,"error":{"code":"revoke_failed","message":"The OAuth connection could not be revoked."}}}}}}},"502":{"description":"tool_failed: The upstream tool threw while executing. Reserved credits are refunded automatically. → Retry with backoff; if it persists the integration is down — check status and report.\noauth_callback_failed: The OAuth provider refused the code exchange or the profile lookup. → Restart the connect flow; if it persists the provider app credentials may be misconfigured.\noauth_provider_not_configured: The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY. → The workspace owner should contact support; agents cannot fix this themselves.","content":{"application/json":{"examples":{"tool_failed":{"summary":"tool_failed","value":{"ok":false,"error":{"code":"tool_failed","message":"The upstream tool threw while executing. Reserved credits are refunded automatically."}}},"oauth_callback_failed":{"summary":"oauth_callback_failed","value":{"ok":false,"error":{"code":"oauth_callback_failed","message":"The OAuth provider refused the code exchange or the profile lookup."}}},"oauth_provider_not_configured":{"summary":"oauth_provider_not_configured","value":{"ok":false,"error":{"code":"oauth_provider_not_configured","message":"The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY."}}}}}}},"503":{"description":"metering_unavailable: Credit metering could not be reached, so the call was not authorized or charged. → Retry with backoff; the same idempotency-key is safe to reuse.","content":{"application/json":{"examples":{"metering_unavailable":{"summary":"metering_unavailable","value":{"ok":false,"error":{"code":"metering_unavailable","message":"Credit metering could not be reached, so the call was not authorized or charged."}}}}}}}}}},"/api/public/v1/tools/crawl_site":{"post":{"operationId":"crawl_site","summary":"Crawl site","description":"Crawl a public site starting from one https:// URL and return readable text for that page plus up to nine same-origin pages it links to. Real network calls. Read-only. Costs 6 credit(s).","security":[{"agentKey":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Replay-safe key scoped to your API key. A repeated completed call returns the stored response and is not charged again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Absolute https:// seed URL"},"maxPages":{"type":"number","description":"Total pages to fetch, 1-10. Defaults to 3"},"maxCharsPerPage":{"type":"number","description":"Truncate each page's text to this many characters (default 4000, max 20000)"}},"required":["url"],"additionalProperties":false},"examples":{"default":{"summary":"Example call","value":{"url":"https://example.com","maxPages":3}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"examples":{"default":{"summary":"Success","value":{"ok":true,"requestId":"b0e1c8a2-9f4d-4d0f-9a1e-2c5d7f8e1a30","tool":"crawl_site","demo":false,"credits":{"charged":6,"balance":494},"result":{"ok":true,"seed":"https://example.com","pageCount":2,"pages":[{"url":"https://example.com/","status":200,"title":"Example Domain","text":"Example Domain. This domain is for use in illustrative examples...","chars":208}],"crawledAt":"2026-08-09T20:15:18.358Z"}}}}}}},"401":{"description":"missing_api_key: No Authorization: Bearer header on the request. → Send Authorization: Bearer sk_agent_… , or POST /api/public/v1/signup to mint a key.\ninvalid_api_key: The key is unknown, revoked, or past its rotation grace window. → Rotate with POST /api/public/v1/keys/rotate, or create a new key in the console.\nkey_expired: The key passed the expiry date set by its owner. → Rotate the key or issue a new one in the console.","content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"ok":false,"error":{"code":"missing_api_key","message":"No Authorization: Bearer header on the request."}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"ok":false,"error":{"code":"invalid_api_key","message":"The key is unknown, revoked, or past its rotation grace window."}}},"key_expired":{"summary":"key_expired","value":{"ok":false,"error":{"code":"key_expired","message":"The key passed the expiry date set by its owner."}}}}}}},"402":{"description":"insufficient_credits: The workspace balance is below this tool's price. Nothing was executed or charged. → Pay machine-to-machine: the body carries an x402 accepts[] offer — settle it and retry the same request with an X-PAYMENT header. Humans can instead buy credits via POST /api/public/v1/claim.\npayment_failed: An X-PAYMENT header was supplied but the facilitator could not verify or settle it. → Re-read accepts[0] from a fresh 402, rebuild the payment payload for the exact amount, asset and network, and retry.","content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"ok":false,"error":{"code":"insufficient_credits","message":"The workspace balance is below this tool's price. Nothing was executed or charged.","required":5,"balance":2}}},"payment_failed":{"summary":"payment_failed","value":{"ok":false,"error":{"code":"payment_failed","message":"An X-PAYMENT header was supplied but the facilitator could not verify or settle it."}}}}}}},"403":{"description":"budget_exceeded: The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key. → Wait for the window to roll over, or ask the key owner to raise the cap in the console.\ntool_not_allowed: This key has a tool allowlist that does not include the requested tool. → Call an allowed tool, or ask the key owner to widen the allowlist.\ntool_disabled: The workspace owner has disabled this tool for the org. → Enable the tool in the console, or call a different tool.\ninsufficient_scope: The key is valid but does not carry the tools:invoke scope. → Issue a key with tools:invoke from the console and retry with it.","content":{"application/json":{"examples":{"budget_exceeded":{"summary":"budget_exceeded","value":{"ok":false,"error":{"code":"budget_exceeded","message":"The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key."}}},"tool_not_allowed":{"summary":"tool_not_allowed","value":{"ok":false,"error":{"code":"tool_not_allowed","message":"This key has a tool allowlist that does not include the requested tool."}}},"tool_disabled":{"summary":"tool_disabled","value":{"ok":false,"error":{"code":"tool_disabled","message":"The workspace owner has disabled this tool for the org."}}},"insufficient_scope":{"summary":"insufficient_scope","value":{"ok":false,"error":{"code":"insufficient_scope","message":"The key is valid but does not carry the tools:invoke scope."}}}}}}},"404":{"description":"unknown_tool: No public tool with that name exists in the catalog. → Re-read GET /api/public/v1/tools and use an exact name from the catalog.\napproval_intent_not_found: No approval intent with that id exists in this workspace. → Use the intent_id from the 428 approval object; intents expire after 24 hours.\noauth_provider_unknown: No OAuth provider with that slug is enabled. → GET /api/public/v1/oauth/providers for the supported catalog.\nconnection_not_found: No OAuth connection with that id exists in this workspace. → List connections with GET /api/public/v1/oauth/connections and use a current id.","content":{"application/json":{"examples":{"unknown_tool":{"summary":"unknown_tool","value":{"ok":false,"error":{"code":"unknown_tool","message":"No public tool with that name exists in the catalog."}}},"approval_intent_not_found":{"summary":"approval_intent_not_found","value":{"ok":false,"error":{"code":"approval_intent_not_found","message":"No approval intent with that id exists in this workspace."}}},"oauth_provider_unknown":{"summary":"oauth_provider_unknown","value":{"ok":false,"error":{"code":"oauth_provider_unknown","message":"No OAuth provider with that slug is enabled."}}},"connection_not_found":{"summary":"connection_not_found","value":{"ok":false,"error":{"code":"connection_not_found","message":"No OAuth connection with that id exists in this workspace."}}}}}}},"409":{"description":"request_in_progress: Another call with the same idempotency-key is still executing, or an approved confirmation token is already running. → Wait and retry the same idempotency-key to receive the stored response; do not change the body. If the original request is known to have failed, retry with a new idempotency-key. For a confirmation token, call the tool again with no token to get a fresh preview.\noauth_connection_required: This tool needs a connected third-party account, and none is linked for this workspace. → POST the connect URL from the body with your API key to get an authorization URL, have your operator complete the OAuth flow, then retry the call.","content":{"application/json":{"examples":{"request_in_progress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"Another call with the same idempotency-key is still executing, or an approved confirmation token is already running."}}},"oauth_connection_required":{"summary":"oauth_connection_required","value":{"ok":false,"error":{"code":"oauth_connection_required","message":"This tool needs a connected third-party account, and none is linked for this workspace."}}}}}}},"422":{"description":"invalid_json: The request body was not valid JSON. → Send a JSON object with content-type: application/json.\ninvalid_input: Arguments failed the tool's JSON Schema. No credits were charged. → Fix the fields listed in error.issues[].path and resend.","content":{"application/json":{"examples":{"invalid_json":{"summary":"invalid_json","value":{"ok":false,"error":{"code":"invalid_json","message":"The request body was not valid JSON."}}},"invalid_input":{"summary":"invalid_input","value":{"ok":false,"error":{"code":"invalid_input","message":"Arguments failed the tool's JSON Schema. No credits were charged."}}}}}}},"429":{"description":"rate_limited: Over 60 calls per minute for this API key. → Back off ~1 minute, or mint additional keys for parallel workers.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Over 60 calls per minute for this API key."}}}}}}},"500":{"description":"oauth_authorize_failed: The OAuth authorization URL could not be generated. → Retry; if it persists, check that the provider is still enabled.\ncatalog_unavailable: The OAuth provider catalog could not be loaded. → Retry shortly.\nconnections_unavailable: The workspace's OAuth connections could not be listed. → Retry shortly.\nrevoke_failed: The OAuth connection could not be revoked. → Retry; the connection remains active until revocation succeeds.","content":{"application/json":{"examples":{"oauth_authorize_failed":{"summary":"oauth_authorize_failed","value":{"ok":false,"error":{"code":"oauth_authorize_failed","message":"The OAuth authorization URL could not be generated."}}},"catalog_unavailable":{"summary":"catalog_unavailable","value":{"ok":false,"error":{"code":"catalog_unavailable","message":"The OAuth provider catalog could not be loaded."}}},"connections_unavailable":{"summary":"connections_unavailable","value":{"ok":false,"error":{"code":"connections_unavailable","message":"The workspace's OAuth connections could not be listed."}}},"revoke_failed":{"summary":"revoke_failed","value":{"ok":false,"error":{"code":"revoke_failed","message":"The OAuth connection could not be revoked."}}}}}}},"502":{"description":"tool_failed: The upstream tool threw while executing. Reserved credits are refunded automatically. → Retry with backoff; if it persists the integration is down — check status and report.\noauth_callback_failed: The OAuth provider refused the code exchange or the profile lookup. → Restart the connect flow; if it persists the provider app credentials may be misconfigured.\noauth_provider_not_configured: The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY. → The workspace owner should contact support; agents cannot fix this themselves.","content":{"application/json":{"examples":{"tool_failed":{"summary":"tool_failed","value":{"ok":false,"error":{"code":"tool_failed","message":"The upstream tool threw while executing. Reserved credits are refunded automatically."}}},"oauth_callback_failed":{"summary":"oauth_callback_failed","value":{"ok":false,"error":{"code":"oauth_callback_failed","message":"The OAuth provider refused the code exchange or the profile lookup."}}},"oauth_provider_not_configured":{"summary":"oauth_provider_not_configured","value":{"ok":false,"error":{"code":"oauth_provider_not_configured","message":"The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY."}}}}}}},"503":{"description":"metering_unavailable: Credit metering could not be reached, so the call was not authorized or charged. → Retry with backoff; the same idempotency-key is safe to reuse.","content":{"application/json":{"examples":{"metering_unavailable":{"summary":"metering_unavailable","value":{"ok":false,"error":{"code":"metering_unavailable","message":"Credit metering could not be reached, so the call was not authorized or charged."}}}}}}}}}},"/api/public/v1/tools/extract_structured":{"post":{"operationId":"extract_structured","summary":"Extract structured data","description":"Extract named fields as JSON from a public URL or supplied text, using a server-side model. Returns one value per requested field, or null when absent. Read-only. Costs 8 credit(s).","security":[{"agentKey":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Replay-safe key scoped to your API key. A repeated completed call returns the stored response and is not charged again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"string"},"description":"Field names to extract, e.g. [\"companyName\", \"pricingModel\"]"},"url":{"type":"string","description":"Absolute https:// URL to read. Required unless text is given"},"text":{"type":"string","description":"Raw text to extract from instead of fetching a URL"},"instruction":{"type":"string","description":"Optional extra guidance for the extraction"}},"required":["fields"],"additionalProperties":false},"examples":{"default":{"summary":"Example call","value":{"url":"https://example.com","fields":["title","purpose"]}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"examples":{"default":{"summary":"Success","value":{"ok":true,"requestId":"b0e1c8a2-9f4d-4d0f-9a1e-2c5d7f8e1a30","tool":"extract_structured","demo":false,"credits":{"charged":8,"balance":492},"result":{"ok":true,"sourceUrl":"https://example.com/","fields":{"title":"Example Domain","purpose":"Illustrative examples in documents"},"missing":[],"extractedAt":"2026-08-09T20:15:18.358Z"}}}}}}},"401":{"description":"missing_api_key: No Authorization: Bearer header on the request. → Send Authorization: Bearer sk_agent_… , or POST /api/public/v1/signup to mint a key.\ninvalid_api_key: The key is unknown, revoked, or past its rotation grace window. → Rotate with POST /api/public/v1/keys/rotate, or create a new key in the console.\nkey_expired: The key passed the expiry date set by its owner. → Rotate the key or issue a new one in the console.","content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"ok":false,"error":{"code":"missing_api_key","message":"No Authorization: Bearer header on the request."}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"ok":false,"error":{"code":"invalid_api_key","message":"The key is unknown, revoked, or past its rotation grace window."}}},"key_expired":{"summary":"key_expired","value":{"ok":false,"error":{"code":"key_expired","message":"The key passed the expiry date set by its owner."}}}}}}},"402":{"description":"insufficient_credits: The workspace balance is below this tool's price. Nothing was executed or charged. → Pay machine-to-machine: the body carries an x402 accepts[] offer — settle it and retry the same request with an X-PAYMENT header. Humans can instead buy credits via POST /api/public/v1/claim.\npayment_failed: An X-PAYMENT header was supplied but the facilitator could not verify or settle it. → Re-read accepts[0] from a fresh 402, rebuild the payment payload for the exact amount, asset and network, and retry.","content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"ok":false,"error":{"code":"insufficient_credits","message":"The workspace balance is below this tool's price. Nothing was executed or charged.","required":5,"balance":2}}},"payment_failed":{"summary":"payment_failed","value":{"ok":false,"error":{"code":"payment_failed","message":"An X-PAYMENT header was supplied but the facilitator could not verify or settle it."}}}}}}},"403":{"description":"budget_exceeded: The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key. → Wait for the window to roll over, or ask the key owner to raise the cap in the console.\ntool_not_allowed: This key has a tool allowlist that does not include the requested tool. → Call an allowed tool, or ask the key owner to widen the allowlist.\ntool_disabled: The workspace owner has disabled this tool for the org. → Enable the tool in the console, or call a different tool.\ninsufficient_scope: The key is valid but does not carry the tools:invoke scope. → Issue a key with tools:invoke from the console and retry with it.","content":{"application/json":{"examples":{"budget_exceeded":{"summary":"budget_exceeded","value":{"ok":false,"error":{"code":"budget_exceeded","message":"The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key."}}},"tool_not_allowed":{"summary":"tool_not_allowed","value":{"ok":false,"error":{"code":"tool_not_allowed","message":"This key has a tool allowlist that does not include the requested tool."}}},"tool_disabled":{"summary":"tool_disabled","value":{"ok":false,"error":{"code":"tool_disabled","message":"The workspace owner has disabled this tool for the org."}}},"insufficient_scope":{"summary":"insufficient_scope","value":{"ok":false,"error":{"code":"insufficient_scope","message":"The key is valid but does not carry the tools:invoke scope."}}}}}}},"404":{"description":"unknown_tool: No public tool with that name exists in the catalog. → Re-read GET /api/public/v1/tools and use an exact name from the catalog.\napproval_intent_not_found: No approval intent with that id exists in this workspace. → Use the intent_id from the 428 approval object; intents expire after 24 hours.\noauth_provider_unknown: No OAuth provider with that slug is enabled. → GET /api/public/v1/oauth/providers for the supported catalog.\nconnection_not_found: No OAuth connection with that id exists in this workspace. → List connections with GET /api/public/v1/oauth/connections and use a current id.","content":{"application/json":{"examples":{"unknown_tool":{"summary":"unknown_tool","value":{"ok":false,"error":{"code":"unknown_tool","message":"No public tool with that name exists in the catalog."}}},"approval_intent_not_found":{"summary":"approval_intent_not_found","value":{"ok":false,"error":{"code":"approval_intent_not_found","message":"No approval intent with that id exists in this workspace."}}},"oauth_provider_unknown":{"summary":"oauth_provider_unknown","value":{"ok":false,"error":{"code":"oauth_provider_unknown","message":"No OAuth provider with that slug is enabled."}}},"connection_not_found":{"summary":"connection_not_found","value":{"ok":false,"error":{"code":"connection_not_found","message":"No OAuth connection with that id exists in this workspace."}}}}}}},"409":{"description":"request_in_progress: Another call with the same idempotency-key is still executing, or an approved confirmation token is already running. → Wait and retry the same idempotency-key to receive the stored response; do not change the body. If the original request is known to have failed, retry with a new idempotency-key. For a confirmation token, call the tool again with no token to get a fresh preview.\noauth_connection_required: This tool needs a connected third-party account, and none is linked for this workspace. → POST the connect URL from the body with your API key to get an authorization URL, have your operator complete the OAuth flow, then retry the call.","content":{"application/json":{"examples":{"request_in_progress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"Another call with the same idempotency-key is still executing, or an approved confirmation token is already running."}}},"oauth_connection_required":{"summary":"oauth_connection_required","value":{"ok":false,"error":{"code":"oauth_connection_required","message":"This tool needs a connected third-party account, and none is linked for this workspace."}}}}}}},"422":{"description":"invalid_json: The request body was not valid JSON. → Send a JSON object with content-type: application/json.\ninvalid_input: Arguments failed the tool's JSON Schema. No credits were charged. → Fix the fields listed in error.issues[].path and resend.","content":{"application/json":{"examples":{"invalid_json":{"summary":"invalid_json","value":{"ok":false,"error":{"code":"invalid_json","message":"The request body was not valid JSON."}}},"invalid_input":{"summary":"invalid_input","value":{"ok":false,"error":{"code":"invalid_input","message":"Arguments failed the tool's JSON Schema. No credits were charged."}}}}}}},"429":{"description":"rate_limited: Over 60 calls per minute for this API key. → Back off ~1 minute, or mint additional keys for parallel workers.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Over 60 calls per minute for this API key."}}}}}}},"500":{"description":"oauth_authorize_failed: The OAuth authorization URL could not be generated. → Retry; if it persists, check that the provider is still enabled.\ncatalog_unavailable: The OAuth provider catalog could not be loaded. → Retry shortly.\nconnections_unavailable: The workspace's OAuth connections could not be listed. → Retry shortly.\nrevoke_failed: The OAuth connection could not be revoked. → Retry; the connection remains active until revocation succeeds.","content":{"application/json":{"examples":{"oauth_authorize_failed":{"summary":"oauth_authorize_failed","value":{"ok":false,"error":{"code":"oauth_authorize_failed","message":"The OAuth authorization URL could not be generated."}}},"catalog_unavailable":{"summary":"catalog_unavailable","value":{"ok":false,"error":{"code":"catalog_unavailable","message":"The OAuth provider catalog could not be loaded."}}},"connections_unavailable":{"summary":"connections_unavailable","value":{"ok":false,"error":{"code":"connections_unavailable","message":"The workspace's OAuth connections could not be listed."}}},"revoke_failed":{"summary":"revoke_failed","value":{"ok":false,"error":{"code":"revoke_failed","message":"The OAuth connection could not be revoked."}}}}}}},"502":{"description":"tool_failed: The upstream tool threw while executing. Reserved credits are refunded automatically. → Retry with backoff; if it persists the integration is down — check status and report.\noauth_callback_failed: The OAuth provider refused the code exchange or the profile lookup. → Restart the connect flow; if it persists the provider app credentials may be misconfigured.\noauth_provider_not_configured: The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY. → The workspace owner should contact support; agents cannot fix this themselves.","content":{"application/json":{"examples":{"tool_failed":{"summary":"tool_failed","value":{"ok":false,"error":{"code":"tool_failed","message":"The upstream tool threw while executing. Reserved credits are refunded automatically."}}},"oauth_callback_failed":{"summary":"oauth_callback_failed","value":{"ok":false,"error":{"code":"oauth_callback_failed","message":"The OAuth provider refused the code exchange or the profile lookup."}}},"oauth_provider_not_configured":{"summary":"oauth_provider_not_configured","value":{"ok":false,"error":{"code":"oauth_provider_not_configured","message":"The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY."}}}}}}},"503":{"description":"metering_unavailable: Credit metering could not be reached, so the call was not authorized or charged. → Retry with backoff; the same idempotency-key is safe to reuse.","content":{"application/json":{"examples":{"metering_unavailable":{"summary":"metering_unavailable","value":{"ok":false,"error":{"code":"metering_unavailable","message":"Credit metering could not be reached, so the call was not authorized or charged."}}}}}}}}}},"/api/public/v1/tools/search_web":{"post":{"operationId":"search_web","summary":"Search web","description":"Search the public web and return ranked results with titles, snippets, and source URLs. Uses a server-side search API. Read-only. Costs 4 credit(s).","security":[{"agentKey":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Replay-safe key scoped to your API key. A repeated completed call returns the stored response and is not charged again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Natural language search query"},"maxResults":{"type":"number","description":"Number of results to return, 1-20. Defaults to 5"},"includeAnswer":{"type":"boolean","description":"Include a short AI-generated answer based on the results. Defaults to false"}},"required":["query"],"additionalProperties":false},"examples":{"default":{"summary":"Example call","value":{"query":"x402 payment protocol summary"}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"examples":{"default":{"summary":"Success","value":{"ok":true,"requestId":"b0e1c8a2-9f4d-4d0f-9a1e-2c5d7f8e1a30","tool":"search_web","demo":false,"credits":{"charged":4,"balance":496},"result":{"ok":true,"query":"x402 payment protocol summary","results":[{"title":"x402 - Machine-payable HTTP","url":"https://x402.org","content":"x402 is a protocol for machine payments over HTTP using stablecoins...","score":0.94}],"answer":"x402 lets servers request on-chain payment by returning HTTP 402.","searchedAt":"2026-08-09T20:15:18.358Z"}}}}}}},"401":{"description":"missing_api_key: No Authorization: Bearer header on the request. → Send Authorization: Bearer sk_agent_… , or POST /api/public/v1/signup to mint a key.\ninvalid_api_key: The key is unknown, revoked, or past its rotation grace window. → Rotate with POST /api/public/v1/keys/rotate, or create a new key in the console.\nkey_expired: The key passed the expiry date set by its owner. → Rotate the key or issue a new one in the console.","content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"ok":false,"error":{"code":"missing_api_key","message":"No Authorization: Bearer header on the request."}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"ok":false,"error":{"code":"invalid_api_key","message":"The key is unknown, revoked, or past its rotation grace window."}}},"key_expired":{"summary":"key_expired","value":{"ok":false,"error":{"code":"key_expired","message":"The key passed the expiry date set by its owner."}}}}}}},"402":{"description":"insufficient_credits: The workspace balance is below this tool's price. Nothing was executed or charged. → Pay machine-to-machine: the body carries an x402 accepts[] offer — settle it and retry the same request with an X-PAYMENT header. Humans can instead buy credits via POST /api/public/v1/claim.\npayment_failed: An X-PAYMENT header was supplied but the facilitator could not verify or settle it. → Re-read accepts[0] from a fresh 402, rebuild the payment payload for the exact amount, asset and network, and retry.","content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"ok":false,"error":{"code":"insufficient_credits","message":"The workspace balance is below this tool's price. Nothing was executed or charged.","required":5,"balance":2}}},"payment_failed":{"summary":"payment_failed","value":{"ok":false,"error":{"code":"payment_failed","message":"An X-PAYMENT header was supplied but the facilitator could not verify or settle it."}}}}}}},"403":{"description":"budget_exceeded: The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key. → Wait for the window to roll over, or ask the key owner to raise the cap in the console.\ntool_not_allowed: This key has a tool allowlist that does not include the requested tool. → Call an allowed tool, or ask the key owner to widen the allowlist.\ntool_disabled: The workspace owner has disabled this tool for the org. → Enable the tool in the console, or call a different tool.\ninsufficient_scope: The key is valid but does not carry the tools:invoke scope. → Issue a key with tools:invoke from the console and retry with it.","content":{"application/json":{"examples":{"budget_exceeded":{"summary":"budget_exceeded","value":{"ok":false,"error":{"code":"budget_exceeded","message":"The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key."}}},"tool_not_allowed":{"summary":"tool_not_allowed","value":{"ok":false,"error":{"code":"tool_not_allowed","message":"This key has a tool allowlist that does not include the requested tool."}}},"tool_disabled":{"summary":"tool_disabled","value":{"ok":false,"error":{"code":"tool_disabled","message":"The workspace owner has disabled this tool for the org."}}},"insufficient_scope":{"summary":"insufficient_scope","value":{"ok":false,"error":{"code":"insufficient_scope","message":"The key is valid but does not carry the tools:invoke scope."}}}}}}},"404":{"description":"unknown_tool: No public tool with that name exists in the catalog. → Re-read GET /api/public/v1/tools and use an exact name from the catalog.\napproval_intent_not_found: No approval intent with that id exists in this workspace. → Use the intent_id from the 428 approval object; intents expire after 24 hours.\noauth_provider_unknown: No OAuth provider with that slug is enabled. → GET /api/public/v1/oauth/providers for the supported catalog.\nconnection_not_found: No OAuth connection with that id exists in this workspace. → List connections with GET /api/public/v1/oauth/connections and use a current id.","content":{"application/json":{"examples":{"unknown_tool":{"summary":"unknown_tool","value":{"ok":false,"error":{"code":"unknown_tool","message":"No public tool with that name exists in the catalog."}}},"approval_intent_not_found":{"summary":"approval_intent_not_found","value":{"ok":false,"error":{"code":"approval_intent_not_found","message":"No approval intent with that id exists in this workspace."}}},"oauth_provider_unknown":{"summary":"oauth_provider_unknown","value":{"ok":false,"error":{"code":"oauth_provider_unknown","message":"No OAuth provider with that slug is enabled."}}},"connection_not_found":{"summary":"connection_not_found","value":{"ok":false,"error":{"code":"connection_not_found","message":"No OAuth connection with that id exists in this workspace."}}}}}}},"409":{"description":"request_in_progress: Another call with the same idempotency-key is still executing, or an approved confirmation token is already running. → Wait and retry the same idempotency-key to receive the stored response; do not change the body. If the original request is known to have failed, retry with a new idempotency-key. For a confirmation token, call the tool again with no token to get a fresh preview.\noauth_connection_required: This tool needs a connected third-party account, and none is linked for this workspace. → POST the connect URL from the body with your API key to get an authorization URL, have your operator complete the OAuth flow, then retry the call.","content":{"application/json":{"examples":{"request_in_progress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"Another call with the same idempotency-key is still executing, or an approved confirmation token is already running."}}},"oauth_connection_required":{"summary":"oauth_connection_required","value":{"ok":false,"error":{"code":"oauth_connection_required","message":"This tool needs a connected third-party account, and none is linked for this workspace."}}}}}}},"422":{"description":"invalid_json: The request body was not valid JSON. → Send a JSON object with content-type: application/json.\ninvalid_input: Arguments failed the tool's JSON Schema. No credits were charged. → Fix the fields listed in error.issues[].path and resend.","content":{"application/json":{"examples":{"invalid_json":{"summary":"invalid_json","value":{"ok":false,"error":{"code":"invalid_json","message":"The request body was not valid JSON."}}},"invalid_input":{"summary":"invalid_input","value":{"ok":false,"error":{"code":"invalid_input","message":"Arguments failed the tool's JSON Schema. No credits were charged."}}}}}}},"429":{"description":"rate_limited: Over 60 calls per minute for this API key. → Back off ~1 minute, or mint additional keys for parallel workers.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Over 60 calls per minute for this API key."}}}}}}},"500":{"description":"oauth_authorize_failed: The OAuth authorization URL could not be generated. → Retry; if it persists, check that the provider is still enabled.\ncatalog_unavailable: The OAuth provider catalog could not be loaded. → Retry shortly.\nconnections_unavailable: The workspace's OAuth connections could not be listed. → Retry shortly.\nrevoke_failed: The OAuth connection could not be revoked. → Retry; the connection remains active until revocation succeeds.","content":{"application/json":{"examples":{"oauth_authorize_failed":{"summary":"oauth_authorize_failed","value":{"ok":false,"error":{"code":"oauth_authorize_failed","message":"The OAuth authorization URL could not be generated."}}},"catalog_unavailable":{"summary":"catalog_unavailable","value":{"ok":false,"error":{"code":"catalog_unavailable","message":"The OAuth provider catalog could not be loaded."}}},"connections_unavailable":{"summary":"connections_unavailable","value":{"ok":false,"error":{"code":"connections_unavailable","message":"The workspace's OAuth connections could not be listed."}}},"revoke_failed":{"summary":"revoke_failed","value":{"ok":false,"error":{"code":"revoke_failed","message":"The OAuth connection could not be revoked."}}}}}}},"502":{"description":"tool_failed: The upstream tool threw while executing. Reserved credits are refunded automatically. → Retry with backoff; if it persists the integration is down — check status and report.\noauth_callback_failed: The OAuth provider refused the code exchange or the profile lookup. → Restart the connect flow; if it persists the provider app credentials may be misconfigured.\noauth_provider_not_configured: The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY. → The workspace owner should contact support; agents cannot fix this themselves.","content":{"application/json":{"examples":{"tool_failed":{"summary":"tool_failed","value":{"ok":false,"error":{"code":"tool_failed","message":"The upstream tool threw while executing. Reserved credits are refunded automatically."}}},"oauth_callback_failed":{"summary":"oauth_callback_failed","value":{"ok":false,"error":{"code":"oauth_callback_failed","message":"The OAuth provider refused the code exchange or the profile lookup."}}},"oauth_provider_not_configured":{"summary":"oauth_provider_not_configured","value":{"ok":false,"error":{"code":"oauth_provider_not_configured","message":"The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY."}}}}}}},"503":{"description":"metering_unavailable: Credit metering could not be reached, so the call was not authorized or charged. → Retry with backoff; the same idempotency-key is safe to reuse.","content":{"application/json":{"examples":{"metering_unavailable":{"summary":"metering_unavailable","value":{"ok":false,"error":{"code":"metering_unavailable","message":"Credit metering could not be reached, so the call was not authorized or charged."}}}}}}}}}},"/api/public/v1/tools/search_knowledge_base":{"post":{"operationId":"search_knowledge_base","summary":"Search knowledge base","description":"Search this workspace's uploaded documents using semantic similarity. Returns the most relevant text chunks with document titles and source URLs. Read-only. Costs 3 credit(s).","security":[{"agentKey":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Replay-safe key scoped to your API key. A repeated completed call returns the stored response and is not charged again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Natural language search query"},"maxResults":{"type":"number","description":"Number of chunks to return, 1-20. Defaults to 5"},"documentIds":{"type":"array","items":{"type":"string"},"description":"Optional list of document IDs to restrict the search to"}},"required":["query"],"additionalProperties":false},"examples":{"default":{"summary":"Example call","value":{"query":"refund policy"}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"examples":{"default":{"summary":"Success","value":{"ok":true,"requestId":"b0e1c8a2-9f4d-4d0f-9a1e-2c5d7f8e1a30","tool":"search_knowledge_base","demo":false,"credits":{"charged":3,"balance":497},"result":{"ok":true,"matches":[{"documentId":"doc_...","chunkIndex":0,"title":"Refund policy","sourceUrl":null,"content":"Refunds are issued within 14 days of purchase for annual plans...","similarity":0.91}]}}}}}}},"401":{"description":"missing_api_key: No Authorization: Bearer header on the request. → Send Authorization: Bearer sk_agent_… , or POST /api/public/v1/signup to mint a key.\ninvalid_api_key: The key is unknown, revoked, or past its rotation grace window. → Rotate with POST /api/public/v1/keys/rotate, or create a new key in the console.\nkey_expired: The key passed the expiry date set by its owner. → Rotate the key or issue a new one in the console.","content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"ok":false,"error":{"code":"missing_api_key","message":"No Authorization: Bearer header on the request."}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"ok":false,"error":{"code":"invalid_api_key","message":"The key is unknown, revoked, or past its rotation grace window."}}},"key_expired":{"summary":"key_expired","value":{"ok":false,"error":{"code":"key_expired","message":"The key passed the expiry date set by its owner."}}}}}}},"402":{"description":"insufficient_credits: The workspace balance is below this tool's price. Nothing was executed or charged. → Pay machine-to-machine: the body carries an x402 accepts[] offer — settle it and retry the same request with an X-PAYMENT header. Humans can instead buy credits via POST /api/public/v1/claim.\npayment_failed: An X-PAYMENT header was supplied but the facilitator could not verify or settle it. → Re-read accepts[0] from a fresh 402, rebuild the payment payload for the exact amount, asset and network, and retry.","content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"ok":false,"error":{"code":"insufficient_credits","message":"The workspace balance is below this tool's price. Nothing was executed or charged.","required":5,"balance":2}}},"payment_failed":{"summary":"payment_failed","value":{"ok":false,"error":{"code":"payment_failed","message":"An X-PAYMENT header was supplied but the facilitator could not verify or settle it."}}}}}}},"403":{"description":"budget_exceeded: The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key. → Wait for the window to roll over, or ask the key owner to raise the cap in the console.\ntool_not_allowed: This key has a tool allowlist that does not include the requested tool. → Call an allowed tool, or ask the key owner to widen the allowlist.\ntool_disabled: The workspace owner has disabled this tool for the org. → Enable the tool in the console, or call a different tool.\ninsufficient_scope: The key is valid but does not carry the tools:invoke scope. → Issue a key with tools:invoke from the console and retry with it.","content":{"application/json":{"examples":{"budget_exceeded":{"summary":"budget_exceeded","value":{"ok":false,"error":{"code":"budget_exceeded","message":"The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key."}}},"tool_not_allowed":{"summary":"tool_not_allowed","value":{"ok":false,"error":{"code":"tool_not_allowed","message":"This key has a tool allowlist that does not include the requested tool."}}},"tool_disabled":{"summary":"tool_disabled","value":{"ok":false,"error":{"code":"tool_disabled","message":"The workspace owner has disabled this tool for the org."}}},"insufficient_scope":{"summary":"insufficient_scope","value":{"ok":false,"error":{"code":"insufficient_scope","message":"The key is valid but does not carry the tools:invoke scope."}}}}}}},"404":{"description":"unknown_tool: No public tool with that name exists in the catalog. → Re-read GET /api/public/v1/tools and use an exact name from the catalog.\napproval_intent_not_found: No approval intent with that id exists in this workspace. → Use the intent_id from the 428 approval object; intents expire after 24 hours.\noauth_provider_unknown: No OAuth provider with that slug is enabled. → GET /api/public/v1/oauth/providers for the supported catalog.\nconnection_not_found: No OAuth connection with that id exists in this workspace. → List connections with GET /api/public/v1/oauth/connections and use a current id.","content":{"application/json":{"examples":{"unknown_tool":{"summary":"unknown_tool","value":{"ok":false,"error":{"code":"unknown_tool","message":"No public tool with that name exists in the catalog."}}},"approval_intent_not_found":{"summary":"approval_intent_not_found","value":{"ok":false,"error":{"code":"approval_intent_not_found","message":"No approval intent with that id exists in this workspace."}}},"oauth_provider_unknown":{"summary":"oauth_provider_unknown","value":{"ok":false,"error":{"code":"oauth_provider_unknown","message":"No OAuth provider with that slug is enabled."}}},"connection_not_found":{"summary":"connection_not_found","value":{"ok":false,"error":{"code":"connection_not_found","message":"No OAuth connection with that id exists in this workspace."}}}}}}},"409":{"description":"request_in_progress: Another call with the same idempotency-key is still executing, or an approved confirmation token is already running. → Wait and retry the same idempotency-key to receive the stored response; do not change the body. If the original request is known to have failed, retry with a new idempotency-key. For a confirmation token, call the tool again with no token to get a fresh preview.\noauth_connection_required: This tool needs a connected third-party account, and none is linked for this workspace. → POST the connect URL from the body with your API key to get an authorization URL, have your operator complete the OAuth flow, then retry the call.","content":{"application/json":{"examples":{"request_in_progress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"Another call with the same idempotency-key is still executing, or an approved confirmation token is already running."}}},"oauth_connection_required":{"summary":"oauth_connection_required","value":{"ok":false,"error":{"code":"oauth_connection_required","message":"This tool needs a connected third-party account, and none is linked for this workspace."}}}}}}},"422":{"description":"invalid_json: The request body was not valid JSON. → Send a JSON object with content-type: application/json.\ninvalid_input: Arguments failed the tool's JSON Schema. No credits were charged. → Fix the fields listed in error.issues[].path and resend.","content":{"application/json":{"examples":{"invalid_json":{"summary":"invalid_json","value":{"ok":false,"error":{"code":"invalid_json","message":"The request body was not valid JSON."}}},"invalid_input":{"summary":"invalid_input","value":{"ok":false,"error":{"code":"invalid_input","message":"Arguments failed the tool's JSON Schema. No credits were charged."}}}}}}},"429":{"description":"rate_limited: Over 60 calls per minute for this API key. → Back off ~1 minute, or mint additional keys for parallel workers.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Over 60 calls per minute for this API key."}}}}}}},"500":{"description":"oauth_authorize_failed: The OAuth authorization URL could not be generated. → Retry; if it persists, check that the provider is still enabled.\ncatalog_unavailable: The OAuth provider catalog could not be loaded. → Retry shortly.\nconnections_unavailable: The workspace's OAuth connections could not be listed. → Retry shortly.\nrevoke_failed: The OAuth connection could not be revoked. → Retry; the connection remains active until revocation succeeds.","content":{"application/json":{"examples":{"oauth_authorize_failed":{"summary":"oauth_authorize_failed","value":{"ok":false,"error":{"code":"oauth_authorize_failed","message":"The OAuth authorization URL could not be generated."}}},"catalog_unavailable":{"summary":"catalog_unavailable","value":{"ok":false,"error":{"code":"catalog_unavailable","message":"The OAuth provider catalog could not be loaded."}}},"connections_unavailable":{"summary":"connections_unavailable","value":{"ok":false,"error":{"code":"connections_unavailable","message":"The workspace's OAuth connections could not be listed."}}},"revoke_failed":{"summary":"revoke_failed","value":{"ok":false,"error":{"code":"revoke_failed","message":"The OAuth connection could not be revoked."}}}}}}},"502":{"description":"tool_failed: The upstream tool threw while executing. Reserved credits are refunded automatically. → Retry with backoff; if it persists the integration is down — check status and report.\noauth_callback_failed: The OAuth provider refused the code exchange or the profile lookup. → Restart the connect flow; if it persists the provider app credentials may be misconfigured.\noauth_provider_not_configured: The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY. → The workspace owner should contact support; agents cannot fix this themselves.","content":{"application/json":{"examples":{"tool_failed":{"summary":"tool_failed","value":{"ok":false,"error":{"code":"tool_failed","message":"The upstream tool threw while executing. Reserved credits are refunded automatically."}}},"oauth_callback_failed":{"summary":"oauth_callback_failed","value":{"ok":false,"error":{"code":"oauth_callback_failed","message":"The OAuth provider refused the code exchange or the profile lookup."}}},"oauth_provider_not_configured":{"summary":"oauth_provider_not_configured","value":{"ok":false,"error":{"code":"oauth_provider_not_configured","message":"The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY."}}}}}}},"503":{"description":"metering_unavailable: Credit metering could not be reached, so the call was not authorized or charged. → Retry with backoff; the same idempotency-key is safe to reuse.","content":{"application/json":{"examples":{"metering_unavailable":{"summary":"metering_unavailable","value":{"ok":false,"error":{"code":"metering_unavailable","message":"Credit metering could not be reached, so the call was not authorized or charged."}}}}}}}}}},"/api/public/v1/tools/execute_code":{"post":{"operationId":"execute_code","summary":"Execute code","description":"Run Python or JavaScript code in a sandboxed E2B environment and return stdout, stderr, and the exit code. Files are ephemeral, but code can make external network requests with side effects. Requires the configured side-effect confirmation flow. Costs 8 credit(s). Side-effecting: the first call returns 428 confirmation_required with a preview and a single-use confirmationToken; resend the identical body with header x-confirmation-token to execute.","security":[{"agentKey":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Replay-safe key scoped to your API key. A repeated completed call returns the stored response and is not charged again."},{"name":"x-confirmation-token","in":"header","required":false,"schema":{"type":"string"},"description":"Single-use token from a prior 428 confirmation_required response, bound to this exact request body. Omit it on the first call to receive the preview and token."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Python or JavaScript code to execute"},"language":{"type":"string","enum":["python","javascript"],"description":"Language. Defaults to python"},"timeout":{"type":"number","description":"Timeout in seconds, 1-300. Defaults to 60"}},"required":["code"],"additionalProperties":false},"examples":{"default":{"summary":"Example call","value":{"code":"print('hello')","language":"python"}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"examples":{"default":{"summary":"Success","value":{"ok":true,"requestId":"b0e1c8a2-9f4d-4d0f-9a1e-2c5d7f8e1a30","tool":"execute_code","demo":false,"credits":{"charged":8,"balance":492},"result":{"ok":true,"language":"python","stdout":"hello\n","stderr":"","exitCode":0,"executedAt":"2026-08-09T20:15:18.358Z"}}}}}}},"401":{"description":"missing_api_key: No Authorization: Bearer header on the request. → Send Authorization: Bearer sk_agent_… , or POST /api/public/v1/signup to mint a key.\ninvalid_api_key: The key is unknown, revoked, or past its rotation grace window. → Rotate with POST /api/public/v1/keys/rotate, or create a new key in the console.\nkey_expired: The key passed the expiry date set by its owner. → Rotate the key or issue a new one in the console.","content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"ok":false,"error":{"code":"missing_api_key","message":"No Authorization: Bearer header on the request."}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"ok":false,"error":{"code":"invalid_api_key","message":"The key is unknown, revoked, or past its rotation grace window."}}},"key_expired":{"summary":"key_expired","value":{"ok":false,"error":{"code":"key_expired","message":"The key passed the expiry date set by its owner."}}}}}}},"402":{"description":"insufficient_credits: The workspace balance is below this tool's price. Nothing was executed or charged. → Pay machine-to-machine: the body carries an x402 accepts[] offer — settle it and retry the same request with an X-PAYMENT header. Humans can instead buy credits via POST /api/public/v1/claim.\npayment_failed: An X-PAYMENT header was supplied but the facilitator could not verify or settle it. → Re-read accepts[0] from a fresh 402, rebuild the payment payload for the exact amount, asset and network, and retry.","content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"ok":false,"error":{"code":"insufficient_credits","message":"The workspace balance is below this tool's price. Nothing was executed or charged.","required":5,"balance":2}}},"payment_failed":{"summary":"payment_failed","value":{"ok":false,"error":{"code":"payment_failed","message":"An X-PAYMENT header was supplied but the facilitator could not verify or settle it."}}}}}}},"403":{"description":"budget_exceeded: The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key. → Wait for the window to roll over, or ask the key owner to raise the cap in the console.\ntool_not_allowed: This key has a tool allowlist that does not include the requested tool. → Call an allowed tool, or ask the key owner to widen the allowlist.\ntool_disabled: The workspace owner has disabled this tool for the org. → Enable the tool in the console, or call a different tool.\ninsufficient_scope: The key is valid but does not carry the tools:invoke scope. → Issue a key with tools:invoke from the console and retry with it.\nconfirmation_invalid: The x-confirmation-token header is unknown or belongs to another workspace. → Call the tool without a token to receive a fresh preview and token, then retry.","content":{"application/json":{"examples":{"budget_exceeded":{"summary":"budget_exceeded","value":{"ok":false,"error":{"code":"budget_exceeded","message":"The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key."}}},"tool_not_allowed":{"summary":"tool_not_allowed","value":{"ok":false,"error":{"code":"tool_not_allowed","message":"This key has a tool allowlist that does not include the requested tool."}}},"tool_disabled":{"summary":"tool_disabled","value":{"ok":false,"error":{"code":"tool_disabled","message":"The workspace owner has disabled this tool for the org."}}},"insufficient_scope":{"summary":"insufficient_scope","value":{"ok":false,"error":{"code":"insufficient_scope","message":"The key is valid but does not carry the tools:invoke scope."}}},"confirmation_invalid":{"summary":"confirmation_invalid","value":{"ok":false,"error":{"code":"confirmation_invalid","message":"The x-confirmation-token header is unknown or belongs to another workspace."}}}}}}},"404":{"description":"unknown_tool: No public tool with that name exists in the catalog. → Re-read GET /api/public/v1/tools and use an exact name from the catalog.\napproval_intent_not_found: No approval intent with that id exists in this workspace. → Use the intent_id from the 428 approval object; intents expire after 24 hours.\noauth_provider_unknown: No OAuth provider with that slug is enabled. → GET /api/public/v1/oauth/providers for the supported catalog.\nconnection_not_found: No OAuth connection with that id exists in this workspace. → List connections with GET /api/public/v1/oauth/connections and use a current id.","content":{"application/json":{"examples":{"unknown_tool":{"summary":"unknown_tool","value":{"ok":false,"error":{"code":"unknown_tool","message":"No public tool with that name exists in the catalog."}}},"approval_intent_not_found":{"summary":"approval_intent_not_found","value":{"ok":false,"error":{"code":"approval_intent_not_found","message":"No approval intent with that id exists in this workspace."}}},"oauth_provider_unknown":{"summary":"oauth_provider_unknown","value":{"ok":false,"error":{"code":"oauth_provider_unknown","message":"No OAuth provider with that slug is enabled."}}},"connection_not_found":{"summary":"connection_not_found","value":{"ok":false,"error":{"code":"connection_not_found","message":"No OAuth connection with that id exists in this workspace."}}}}}}},"409":{"description":"request_in_progress: Another call with the same idempotency-key is still executing, or an approved confirmation token is already running. → Wait and retry the same idempotency-key to receive the stored response; do not change the body. If the original request is known to have failed, retry with a new idempotency-key. For a confirmation token, call the tool again with no token to get a fresh preview.\nconfirmation_mismatch: The token is bound to a specific tool and argument set; this request differs from what was previewed. → Send the exact body that was previewed, or request a new confirmation for the new body.\nconfirmation_used: That confirmation token was already redeemed. Tokens are single-use. → Request a new confirmation for the next call.\noauth_connection_required: This tool needs a connected third-party account, and none is linked for this workspace. → POST the connect URL from the body with your API key to get an authorization URL, have your operator complete the OAuth flow, then retry the call.","content":{"application/json":{"examples":{"request_in_progress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"Another call with the same idempotency-key is still executing, or an approved confirmation token is already running."}}},"confirmation_mismatch":{"summary":"confirmation_mismatch","value":{"ok":false,"error":{"code":"confirmation_mismatch","message":"The token is bound to a specific tool and argument set; this request differs from what was previewed."}}},"confirmation_used":{"summary":"confirmation_used","value":{"ok":false,"error":{"code":"confirmation_used","message":"That confirmation token was already redeemed. Tokens are single-use."}}},"oauth_connection_required":{"summary":"oauth_connection_required","value":{"ok":false,"error":{"code":"oauth_connection_required","message":"This tool needs a connected third-party account, and none is linked for this workspace."}}}}}}},"410":{"description":"confirmation_expired: The confirmation token passed its 10-minute validity window. → Call again without a token to get a new preview and token.","content":{"application/json":{"examples":{"confirmation_expired":{"summary":"confirmation_expired","value":{"ok":false,"error":{"code":"confirmation_expired","message":"The confirmation token passed its 10-minute validity window."}}}}}}},"422":{"description":"invalid_json: The request body was not valid JSON. → Send a JSON object with content-type: application/json.\ninvalid_input: Arguments failed the tool's JSON Schema. No credits were charged. → Fix the fields listed in error.issues[].path and resend.","content":{"application/json":{"examples":{"invalid_json":{"summary":"invalid_json","value":{"ok":false,"error":{"code":"invalid_json","message":"The request body was not valid JSON."}}},"invalid_input":{"summary":"invalid_input","value":{"ok":false,"error":{"code":"invalid_input","message":"Arguments failed the tool's JSON Schema. No credits were charged."}}}}}}},"428":{"description":"confirmation_required: A side-effecting tool was called without a confirmation token. Nothing was executed or charged. → Show error.preview to your operator. Once they approve, repeat the identical request with header x-confirmation-token: <error.confirmationToken>.","content":{"application/json":{"examples":{"confirmation_required":{"summary":"confirmation_required","value":{"ok":false,"error":{"code":"confirmation_required","message":"A side-effecting tool was called without a confirmation token. Nothing was executed or charged."}}}}}}},"429":{"description":"rate_limited: Over 60 calls per minute for this API key. → Back off ~1 minute, or mint additional keys for parallel workers.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Over 60 calls per minute for this API key."}}}}}}},"500":{"description":"oauth_authorize_failed: The OAuth authorization URL could not be generated. → Retry; if it persists, check that the provider is still enabled.\ncatalog_unavailable: The OAuth provider catalog could not be loaded. → Retry shortly.\nconnections_unavailable: The workspace's OAuth connections could not be listed. → Retry shortly.\nrevoke_failed: The OAuth connection could not be revoked. → Retry; the connection remains active until revocation succeeds.","content":{"application/json":{"examples":{"oauth_authorize_failed":{"summary":"oauth_authorize_failed","value":{"ok":false,"error":{"code":"oauth_authorize_failed","message":"The OAuth authorization URL could not be generated."}}},"catalog_unavailable":{"summary":"catalog_unavailable","value":{"ok":false,"error":{"code":"catalog_unavailable","message":"The OAuth provider catalog could not be loaded."}}},"connections_unavailable":{"summary":"connections_unavailable","value":{"ok":false,"error":{"code":"connections_unavailable","message":"The workspace's OAuth connections could not be listed."}}},"revoke_failed":{"summary":"revoke_failed","value":{"ok":false,"error":{"code":"revoke_failed","message":"The OAuth connection could not be revoked."}}}}}}},"502":{"description":"tool_failed: The upstream tool threw while executing. Reserved credits are refunded automatically. → Retry with backoff; if it persists the integration is down — check status and report.\noauth_callback_failed: The OAuth provider refused the code exchange or the profile lookup. → Restart the connect flow; if it persists the provider app credentials may be misconfigured.\noauth_provider_not_configured: The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY. → The workspace owner should contact support; agents cannot fix this themselves.","content":{"application/json":{"examples":{"tool_failed":{"summary":"tool_failed","value":{"ok":false,"error":{"code":"tool_failed","message":"The upstream tool threw while executing. Reserved credits are refunded automatically."}}},"oauth_callback_failed":{"summary":"oauth_callback_failed","value":{"ok":false,"error":{"code":"oauth_callback_failed","message":"The OAuth provider refused the code exchange or the profile lookup."}}},"oauth_provider_not_configured":{"summary":"oauth_provider_not_configured","value":{"ok":false,"error":{"code":"oauth_provider_not_configured","message":"The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY."}}}}}}},"503":{"description":"metering_unavailable: Credit metering could not be reached, so the call was not authorized or charged. → Retry with backoff; the same idempotency-key is safe to reuse.","content":{"application/json":{"examples":{"metering_unavailable":{"summary":"metering_unavailable","value":{"ok":false,"error":{"code":"metering_unavailable","message":"Credit metering could not be reached, so the call was not authorized or charged."}}}}}}}}}},"/api/public/v1/tools/browse_page":{"post":{"operationId":"browse_page","summary":"Browse page","description":"Open a URL in a remote Browserbase browser and return the rendered page as markdown text, including title, status code, and content type. Runs in Browserbase's cloud so it works from serverless runtimes. Costs 10 credit(s).","security":[{"agentKey":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Replay-safe key scoped to your API key. A repeated completed call returns the stored response and is not charged again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"URL to open and render"}},"required":["url"],"additionalProperties":false},"examples":{"default":{"summary":"Example call","value":{"url":"https://example.com"}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"examples":{"default":{"summary":"Success","value":{"ok":true,"requestId":"b0e1c8a2-9f4d-4d0f-9a1e-2c5d7f8e1a30","tool":"browse_page","demo":false,"credits":{"charged":10,"balance":490},"result":{"ok":true,"url":"https://example.com/","statusCode":200,"contentType":"text/markdown","title":"Example Domain","text":"Example Domain\n\nThis domain is for use in illustrative examples...","finishedAt":"2026-08-09T20:15:18.358Z"}}}}}}},"401":{"description":"missing_api_key: No Authorization: Bearer header on the request. → Send Authorization: Bearer sk_agent_… , or POST /api/public/v1/signup to mint a key.\ninvalid_api_key: The key is unknown, revoked, or past its rotation grace window. → Rotate with POST /api/public/v1/keys/rotate, or create a new key in the console.\nkey_expired: The key passed the expiry date set by its owner. → Rotate the key or issue a new one in the console.","content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"ok":false,"error":{"code":"missing_api_key","message":"No Authorization: Bearer header on the request."}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"ok":false,"error":{"code":"invalid_api_key","message":"The key is unknown, revoked, or past its rotation grace window."}}},"key_expired":{"summary":"key_expired","value":{"ok":false,"error":{"code":"key_expired","message":"The key passed the expiry date set by its owner."}}}}}}},"402":{"description":"insufficient_credits: The workspace balance is below this tool's price. Nothing was executed or charged. → Pay machine-to-machine: the body carries an x402 accepts[] offer — settle it and retry the same request with an X-PAYMENT header. Humans can instead buy credits via POST /api/public/v1/claim.\npayment_failed: An X-PAYMENT header was supplied but the facilitator could not verify or settle it. → Re-read accepts[0] from a fresh 402, rebuild the payment payload for the exact amount, asset and network, and retry.","content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"ok":false,"error":{"code":"insufficient_credits","message":"The workspace balance is below this tool's price. Nothing was executed or charged.","required":5,"balance":2}}},"payment_failed":{"summary":"payment_failed","value":{"ok":false,"error":{"code":"payment_failed","message":"An X-PAYMENT header was supplied but the facilitator could not verify or settle it."}}}}}}},"403":{"description":"budget_exceeded: The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key. → Wait for the window to roll over, or ask the key owner to raise the cap in the console.\ntool_not_allowed: This key has a tool allowlist that does not include the requested tool. → Call an allowed tool, or ask the key owner to widen the allowlist.\ntool_disabled: The workspace owner has disabled this tool for the org. → Enable the tool in the console, or call a different tool.\ninsufficient_scope: The key is valid but does not carry the tools:invoke scope. → Issue a key with tools:invoke from the console and retry with it.","content":{"application/json":{"examples":{"budget_exceeded":{"summary":"budget_exceeded","value":{"ok":false,"error":{"code":"budget_exceeded","message":"The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key."}}},"tool_not_allowed":{"summary":"tool_not_allowed","value":{"ok":false,"error":{"code":"tool_not_allowed","message":"This key has a tool allowlist that does not include the requested tool."}}},"tool_disabled":{"summary":"tool_disabled","value":{"ok":false,"error":{"code":"tool_disabled","message":"The workspace owner has disabled this tool for the org."}}},"insufficient_scope":{"summary":"insufficient_scope","value":{"ok":false,"error":{"code":"insufficient_scope","message":"The key is valid but does not carry the tools:invoke scope."}}}}}}},"404":{"description":"unknown_tool: No public tool with that name exists in the catalog. → Re-read GET /api/public/v1/tools and use an exact name from the catalog.\napproval_intent_not_found: No approval intent with that id exists in this workspace. → Use the intent_id from the 428 approval object; intents expire after 24 hours.\noauth_provider_unknown: No OAuth provider with that slug is enabled. → GET /api/public/v1/oauth/providers for the supported catalog.\nconnection_not_found: No OAuth connection with that id exists in this workspace. → List connections with GET /api/public/v1/oauth/connections and use a current id.","content":{"application/json":{"examples":{"unknown_tool":{"summary":"unknown_tool","value":{"ok":false,"error":{"code":"unknown_tool","message":"No public tool with that name exists in the catalog."}}},"approval_intent_not_found":{"summary":"approval_intent_not_found","value":{"ok":false,"error":{"code":"approval_intent_not_found","message":"No approval intent with that id exists in this workspace."}}},"oauth_provider_unknown":{"summary":"oauth_provider_unknown","value":{"ok":false,"error":{"code":"oauth_provider_unknown","message":"No OAuth provider with that slug is enabled."}}},"connection_not_found":{"summary":"connection_not_found","value":{"ok":false,"error":{"code":"connection_not_found","message":"No OAuth connection with that id exists in this workspace."}}}}}}},"409":{"description":"request_in_progress: Another call with the same idempotency-key is still executing, or an approved confirmation token is already running. → Wait and retry the same idempotency-key to receive the stored response; do not change the body. If the original request is known to have failed, retry with a new idempotency-key. For a confirmation token, call the tool again with no token to get a fresh preview.\noauth_connection_required: This tool needs a connected third-party account, and none is linked for this workspace. → POST the connect URL from the body with your API key to get an authorization URL, have your operator complete the OAuth flow, then retry the call.","content":{"application/json":{"examples":{"request_in_progress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"Another call with the same idempotency-key is still executing, or an approved confirmation token is already running."}}},"oauth_connection_required":{"summary":"oauth_connection_required","value":{"ok":false,"error":{"code":"oauth_connection_required","message":"This tool needs a connected third-party account, and none is linked for this workspace."}}}}}}},"422":{"description":"invalid_json: The request body was not valid JSON. → Send a JSON object with content-type: application/json.\ninvalid_input: Arguments failed the tool's JSON Schema. No credits were charged. → Fix the fields listed in error.issues[].path and resend.","content":{"application/json":{"examples":{"invalid_json":{"summary":"invalid_json","value":{"ok":false,"error":{"code":"invalid_json","message":"The request body was not valid JSON."}}},"invalid_input":{"summary":"invalid_input","value":{"ok":false,"error":{"code":"invalid_input","message":"Arguments failed the tool's JSON Schema. No credits were charged."}}}}}}},"429":{"description":"rate_limited: Over 60 calls per minute for this API key. → Back off ~1 minute, or mint additional keys for parallel workers.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Over 60 calls per minute for this API key."}}}}}}},"500":{"description":"oauth_authorize_failed: The OAuth authorization URL could not be generated. → Retry; if it persists, check that the provider is still enabled.\ncatalog_unavailable: The OAuth provider catalog could not be loaded. → Retry shortly.\nconnections_unavailable: The workspace's OAuth connections could not be listed. → Retry shortly.\nrevoke_failed: The OAuth connection could not be revoked. → Retry; the connection remains active until revocation succeeds.","content":{"application/json":{"examples":{"oauth_authorize_failed":{"summary":"oauth_authorize_failed","value":{"ok":false,"error":{"code":"oauth_authorize_failed","message":"The OAuth authorization URL could not be generated."}}},"catalog_unavailable":{"summary":"catalog_unavailable","value":{"ok":false,"error":{"code":"catalog_unavailable","message":"The OAuth provider catalog could not be loaded."}}},"connections_unavailable":{"summary":"connections_unavailable","value":{"ok":false,"error":{"code":"connections_unavailable","message":"The workspace's OAuth connections could not be listed."}}},"revoke_failed":{"summary":"revoke_failed","value":{"ok":false,"error":{"code":"revoke_failed","message":"The OAuth connection could not be revoked."}}}}}}},"502":{"description":"tool_failed: The upstream tool threw while executing. Reserved credits are refunded automatically. → Retry with backoff; if it persists the integration is down — check status and report.\noauth_callback_failed: The OAuth provider refused the code exchange or the profile lookup. → Restart the connect flow; if it persists the provider app credentials may be misconfigured.\noauth_provider_not_configured: The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY. → The workspace owner should contact support; agents cannot fix this themselves.","content":{"application/json":{"examples":{"tool_failed":{"summary":"tool_failed","value":{"ok":false,"error":{"code":"tool_failed","message":"The upstream tool threw while executing. Reserved credits are refunded automatically."}}},"oauth_callback_failed":{"summary":"oauth_callback_failed","value":{"ok":false,"error":{"code":"oauth_callback_failed","message":"The OAuth provider refused the code exchange or the profile lookup."}}},"oauth_provider_not_configured":{"summary":"oauth_provider_not_configured","value":{"ok":false,"error":{"code":"oauth_provider_not_configured","message":"The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY."}}}}}}},"503":{"description":"metering_unavailable: Credit metering could not be reached, so the call was not authorized or charged. → Retry with backoff; the same idempotency-key is safe to reuse.","content":{"application/json":{"examples":{"metering_unavailable":{"summary":"metering_unavailable","value":{"ok":false,"error":{"code":"metering_unavailable","message":"Credit metering could not be reached, so the call was not authorized or charged."}}}}}}}}}},"/api/public/v1/tools/sandbox_search_knowledge_base":{"post":{"operationId":"sandbox_search_knowledge_base","summary":"Search knowledge base (sandbox)","description":"Sandbox: searches a fixed set of fixture documents and returns simulated matches. Free — use it to exercise the API, not for real knowledge. Costs 0 credit(s).","security":[{"agentKey":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Replay-safe key scoped to your API key. A repeated completed call returns the stored response and is not charged again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Natural language search query"}},"required":["query"],"additionalProperties":false},"examples":{"default":{"summary":"Example call","value":{"query":"refund policy"}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"examples":{"default":{"summary":"Success","value":{"ok":true,"requestId":"b0e1c8a2-9f4d-4d0f-9a1e-2c5d7f8e1a30","tool":"sandbox_search_knowledge_base","demo":true,"credits":{"charged":0,"balance":500},"result":{"ok":true,"matches":[{"title":"Refund policy","body":"Refunds are issued within 14 days of purchase for annual plans, pro-rated after that."}]}}}}}}},"401":{"description":"missing_api_key: No Authorization: Bearer header on the request. → Send Authorization: Bearer sk_agent_… , or POST /api/public/v1/signup to mint a key.\ninvalid_api_key: The key is unknown, revoked, or past its rotation grace window. → Rotate with POST /api/public/v1/keys/rotate, or create a new key in the console.\nkey_expired: The key passed the expiry date set by its owner. → Rotate the key or issue a new one in the console.","content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"ok":false,"error":{"code":"missing_api_key","message":"No Authorization: Bearer header on the request."}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"ok":false,"error":{"code":"invalid_api_key","message":"The key is unknown, revoked, or past its rotation grace window."}}},"key_expired":{"summary":"key_expired","value":{"ok":false,"error":{"code":"key_expired","message":"The key passed the expiry date set by its owner."}}}}}}},"402":{"description":"insufficient_credits: The workspace balance is below this tool's price. Nothing was executed or charged. → Pay machine-to-machine: the body carries an x402 accepts[] offer — settle it and retry the same request with an X-PAYMENT header. Humans can instead buy credits via POST /api/public/v1/claim.\npayment_failed: An X-PAYMENT header was supplied but the facilitator could not verify or settle it. → Re-read accepts[0] from a fresh 402, rebuild the payment payload for the exact amount, asset and network, and retry.","content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"ok":false,"error":{"code":"insufficient_credits","message":"The workspace balance is below this tool's price. Nothing was executed or charged.","required":5,"balance":2}}},"payment_failed":{"summary":"payment_failed","value":{"ok":false,"error":{"code":"payment_failed","message":"An X-PAYMENT header was supplied but the facilitator could not verify or settle it."}}}}}}},"403":{"description":"budget_exceeded: The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key. → Wait for the window to roll over, or ask the key owner to raise the cap in the console.\ntool_not_allowed: This key has a tool allowlist that does not include the requested tool. → Call an allowed tool, or ask the key owner to widen the allowlist.\ntool_disabled: The workspace owner has disabled this tool for the org. → Enable the tool in the console, or call a different tool.\ninsufficient_scope: The key is valid but does not carry the tools:invoke scope. → Issue a key with tools:invoke from the console and retry with it.","content":{"application/json":{"examples":{"budget_exceeded":{"summary":"budget_exceeded","value":{"ok":false,"error":{"code":"budget_exceeded","message":"The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key."}}},"tool_not_allowed":{"summary":"tool_not_allowed","value":{"ok":false,"error":{"code":"tool_not_allowed","message":"This key has a tool allowlist that does not include the requested tool."}}},"tool_disabled":{"summary":"tool_disabled","value":{"ok":false,"error":{"code":"tool_disabled","message":"The workspace owner has disabled this tool for the org."}}},"insufficient_scope":{"summary":"insufficient_scope","value":{"ok":false,"error":{"code":"insufficient_scope","message":"The key is valid but does not carry the tools:invoke scope."}}}}}}},"404":{"description":"unknown_tool: No public tool with that name exists in the catalog. → Re-read GET /api/public/v1/tools and use an exact name from the catalog.\napproval_intent_not_found: No approval intent with that id exists in this workspace. → Use the intent_id from the 428 approval object; intents expire after 24 hours.\noauth_provider_unknown: No OAuth provider with that slug is enabled. → GET /api/public/v1/oauth/providers for the supported catalog.\nconnection_not_found: No OAuth connection with that id exists in this workspace. → List connections with GET /api/public/v1/oauth/connections and use a current id.","content":{"application/json":{"examples":{"unknown_tool":{"summary":"unknown_tool","value":{"ok":false,"error":{"code":"unknown_tool","message":"No public tool with that name exists in the catalog."}}},"approval_intent_not_found":{"summary":"approval_intent_not_found","value":{"ok":false,"error":{"code":"approval_intent_not_found","message":"No approval intent with that id exists in this workspace."}}},"oauth_provider_unknown":{"summary":"oauth_provider_unknown","value":{"ok":false,"error":{"code":"oauth_provider_unknown","message":"No OAuth provider with that slug is enabled."}}},"connection_not_found":{"summary":"connection_not_found","value":{"ok":false,"error":{"code":"connection_not_found","message":"No OAuth connection with that id exists in this workspace."}}}}}}},"409":{"description":"request_in_progress: Another call with the same idempotency-key is still executing, or an approved confirmation token is already running. → Wait and retry the same idempotency-key to receive the stored response; do not change the body. If the original request is known to have failed, retry with a new idempotency-key. For a confirmation token, call the tool again with no token to get a fresh preview.\noauth_connection_required: This tool needs a connected third-party account, and none is linked for this workspace. → POST the connect URL from the body with your API key to get an authorization URL, have your operator complete the OAuth flow, then retry the call.","content":{"application/json":{"examples":{"request_in_progress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"Another call with the same idempotency-key is still executing, or an approved confirmation token is already running."}}},"oauth_connection_required":{"summary":"oauth_connection_required","value":{"ok":false,"error":{"code":"oauth_connection_required","message":"This tool needs a connected third-party account, and none is linked for this workspace."}}}}}}},"422":{"description":"invalid_json: The request body was not valid JSON. → Send a JSON object with content-type: application/json.\ninvalid_input: Arguments failed the tool's JSON Schema. No credits were charged. → Fix the fields listed in error.issues[].path and resend.","content":{"application/json":{"examples":{"invalid_json":{"summary":"invalid_json","value":{"ok":false,"error":{"code":"invalid_json","message":"The request body was not valid JSON."}}},"invalid_input":{"summary":"invalid_input","value":{"ok":false,"error":{"code":"invalid_input","message":"Arguments failed the tool's JSON Schema. No credits were charged."}}}}}}},"429":{"description":"rate_limited: Over 60 calls per minute for this API key. → Back off ~1 minute, or mint additional keys for parallel workers.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Over 60 calls per minute for this API key."}}}}}}},"500":{"description":"oauth_authorize_failed: The OAuth authorization URL could not be generated. → Retry; if it persists, check that the provider is still enabled.\ncatalog_unavailable: The OAuth provider catalog could not be loaded. → Retry shortly.\nconnections_unavailable: The workspace's OAuth connections could not be listed. → Retry shortly.\nrevoke_failed: The OAuth connection could not be revoked. → Retry; the connection remains active until revocation succeeds.","content":{"application/json":{"examples":{"oauth_authorize_failed":{"summary":"oauth_authorize_failed","value":{"ok":false,"error":{"code":"oauth_authorize_failed","message":"The OAuth authorization URL could not be generated."}}},"catalog_unavailable":{"summary":"catalog_unavailable","value":{"ok":false,"error":{"code":"catalog_unavailable","message":"The OAuth provider catalog could not be loaded."}}},"connections_unavailable":{"summary":"connections_unavailable","value":{"ok":false,"error":{"code":"connections_unavailable","message":"The workspace's OAuth connections could not be listed."}}},"revoke_failed":{"summary":"revoke_failed","value":{"ok":false,"error":{"code":"revoke_failed","message":"The OAuth connection could not be revoked."}}}}}}},"502":{"description":"tool_failed: The upstream tool threw while executing. Reserved credits are refunded automatically. → Retry with backoff; if it persists the integration is down — check status and report.\noauth_callback_failed: The OAuth provider refused the code exchange or the profile lookup. → Restart the connect flow; if it persists the provider app credentials may be misconfigured.\noauth_provider_not_configured: The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY. → The workspace owner should contact support; agents cannot fix this themselves.","content":{"application/json":{"examples":{"tool_failed":{"summary":"tool_failed","value":{"ok":false,"error":{"code":"tool_failed","message":"The upstream tool threw while executing. Reserved credits are refunded automatically."}}},"oauth_callback_failed":{"summary":"oauth_callback_failed","value":{"ok":false,"error":{"code":"oauth_callback_failed","message":"The OAuth provider refused the code exchange or the profile lookup."}}},"oauth_provider_not_configured":{"summary":"oauth_provider_not_configured","value":{"ok":false,"error":{"code":"oauth_provider_not_configured","message":"The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY."}}}}}}},"503":{"description":"metering_unavailable: Credit metering could not be reached, so the call was not authorized or charged. → Retry with backoff; the same idempotency-key is safe to reuse.","content":{"application/json":{"examples":{"metering_unavailable":{"summary":"metering_unavailable","value":{"ok":false,"error":{"code":"metering_unavailable","message":"Credit metering could not be reached, so the call was not authorized or charged."}}}}}}}}}},"/api/public/v1/tools/sandbox_lookup_crm_contact":{"post":{"operationId":"sandbox_lookup_crm_contact","summary":"Look up CRM contact (sandbox)","description":"Sandbox: returns a fixture CRM contact by email. Free — no real CRM is queried. Costs 0 credit(s).","security":[{"agentKey":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Replay-safe key scoped to your API key. A repeated completed call returns the stored response and is not charged again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Contact email address"}},"required":["email"],"additionalProperties":false},"examples":{"default":{"summary":"Example call","value":{"email":"dana@northwind.io"}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"examples":{"default":{"summary":"Success","value":{"ok":true,"requestId":"b0e1c8a2-9f4d-4d0f-9a1e-2c5d7f8e1a30","tool":"sandbox_lookup_crm_contact","demo":true,"credits":{"charged":0,"balance":500},"result":{"ok":true,"contact":{"id":"c_1024","name":"Dana Whitfield","email":"dana@northwind.io","company":"Northwind","stage":"customer","mrr":4200}}}}}}}},"401":{"description":"missing_api_key: No Authorization: Bearer header on the request. → Send Authorization: Bearer sk_agent_… , or POST /api/public/v1/signup to mint a key.\ninvalid_api_key: The key is unknown, revoked, or past its rotation grace window. → Rotate with POST /api/public/v1/keys/rotate, or create a new key in the console.\nkey_expired: The key passed the expiry date set by its owner. → Rotate the key or issue a new one in the console.","content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"ok":false,"error":{"code":"missing_api_key","message":"No Authorization: Bearer header on the request."}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"ok":false,"error":{"code":"invalid_api_key","message":"The key is unknown, revoked, or past its rotation grace window."}}},"key_expired":{"summary":"key_expired","value":{"ok":false,"error":{"code":"key_expired","message":"The key passed the expiry date set by its owner."}}}}}}},"402":{"description":"insufficient_credits: The workspace balance is below this tool's price. Nothing was executed or charged. → Pay machine-to-machine: the body carries an x402 accepts[] offer — settle it and retry the same request with an X-PAYMENT header. Humans can instead buy credits via POST /api/public/v1/claim.\npayment_failed: An X-PAYMENT header was supplied but the facilitator could not verify or settle it. → Re-read accepts[0] from a fresh 402, rebuild the payment payload for the exact amount, asset and network, and retry.","content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"ok":false,"error":{"code":"insufficient_credits","message":"The workspace balance is below this tool's price. Nothing was executed or charged.","required":5,"balance":2}}},"payment_failed":{"summary":"payment_failed","value":{"ok":false,"error":{"code":"payment_failed","message":"An X-PAYMENT header was supplied but the facilitator could not verify or settle it."}}}}}}},"403":{"description":"budget_exceeded: The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key. → Wait for the window to roll over, or ask the key owner to raise the cap in the console.\ntool_not_allowed: This key has a tool allowlist that does not include the requested tool. → Call an allowed tool, or ask the key owner to widen the allowlist.\ntool_disabled: The workspace owner has disabled this tool for the org. → Enable the tool in the console, or call a different tool.\ninsufficient_scope: The key is valid but does not carry the tools:invoke scope. → Issue a key with tools:invoke from the console and retry with it.","content":{"application/json":{"examples":{"budget_exceeded":{"summary":"budget_exceeded","value":{"ok":false,"error":{"code":"budget_exceeded","message":"The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key."}}},"tool_not_allowed":{"summary":"tool_not_allowed","value":{"ok":false,"error":{"code":"tool_not_allowed","message":"This key has a tool allowlist that does not include the requested tool."}}},"tool_disabled":{"summary":"tool_disabled","value":{"ok":false,"error":{"code":"tool_disabled","message":"The workspace owner has disabled this tool for the org."}}},"insufficient_scope":{"summary":"insufficient_scope","value":{"ok":false,"error":{"code":"insufficient_scope","message":"The key is valid but does not carry the tools:invoke scope."}}}}}}},"404":{"description":"unknown_tool: No public tool with that name exists in the catalog. → Re-read GET /api/public/v1/tools and use an exact name from the catalog.\napproval_intent_not_found: No approval intent with that id exists in this workspace. → Use the intent_id from the 428 approval object; intents expire after 24 hours.\noauth_provider_unknown: No OAuth provider with that slug is enabled. → GET /api/public/v1/oauth/providers for the supported catalog.\nconnection_not_found: No OAuth connection with that id exists in this workspace. → List connections with GET /api/public/v1/oauth/connections and use a current id.","content":{"application/json":{"examples":{"unknown_tool":{"summary":"unknown_tool","value":{"ok":false,"error":{"code":"unknown_tool","message":"No public tool with that name exists in the catalog."}}},"approval_intent_not_found":{"summary":"approval_intent_not_found","value":{"ok":false,"error":{"code":"approval_intent_not_found","message":"No approval intent with that id exists in this workspace."}}},"oauth_provider_unknown":{"summary":"oauth_provider_unknown","value":{"ok":false,"error":{"code":"oauth_provider_unknown","message":"No OAuth provider with that slug is enabled."}}},"connection_not_found":{"summary":"connection_not_found","value":{"ok":false,"error":{"code":"connection_not_found","message":"No OAuth connection with that id exists in this workspace."}}}}}}},"409":{"description":"request_in_progress: Another call with the same idempotency-key is still executing, or an approved confirmation token is already running. → Wait and retry the same idempotency-key to receive the stored response; do not change the body. If the original request is known to have failed, retry with a new idempotency-key. For a confirmation token, call the tool again with no token to get a fresh preview.\noauth_connection_required: This tool needs a connected third-party account, and none is linked for this workspace. → POST the connect URL from the body with your API key to get an authorization URL, have your operator complete the OAuth flow, then retry the call.","content":{"application/json":{"examples":{"request_in_progress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"Another call with the same idempotency-key is still executing, or an approved confirmation token is already running."}}},"oauth_connection_required":{"summary":"oauth_connection_required","value":{"ok":false,"error":{"code":"oauth_connection_required","message":"This tool needs a connected third-party account, and none is linked for this workspace."}}}}}}},"422":{"description":"invalid_json: The request body was not valid JSON. → Send a JSON object with content-type: application/json.\ninvalid_input: Arguments failed the tool's JSON Schema. No credits were charged. → Fix the fields listed in error.issues[].path and resend.","content":{"application/json":{"examples":{"invalid_json":{"summary":"invalid_json","value":{"ok":false,"error":{"code":"invalid_json","message":"The request body was not valid JSON."}}},"invalid_input":{"summary":"invalid_input","value":{"ok":false,"error":{"code":"invalid_input","message":"Arguments failed the tool's JSON Schema. No credits were charged."}}}}}}},"429":{"description":"rate_limited: Over 60 calls per minute for this API key. → Back off ~1 minute, or mint additional keys for parallel workers.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Over 60 calls per minute for this API key."}}}}}}},"500":{"description":"oauth_authorize_failed: The OAuth authorization URL could not be generated. → Retry; if it persists, check that the provider is still enabled.\ncatalog_unavailable: The OAuth provider catalog could not be loaded. → Retry shortly.\nconnections_unavailable: The workspace's OAuth connections could not be listed. → Retry shortly.\nrevoke_failed: The OAuth connection could not be revoked. → Retry; the connection remains active until revocation succeeds.","content":{"application/json":{"examples":{"oauth_authorize_failed":{"summary":"oauth_authorize_failed","value":{"ok":false,"error":{"code":"oauth_authorize_failed","message":"The OAuth authorization URL could not be generated."}}},"catalog_unavailable":{"summary":"catalog_unavailable","value":{"ok":false,"error":{"code":"catalog_unavailable","message":"The OAuth provider catalog could not be loaded."}}},"connections_unavailable":{"summary":"connections_unavailable","value":{"ok":false,"error":{"code":"connections_unavailable","message":"The workspace's OAuth connections could not be listed."}}},"revoke_failed":{"summary":"revoke_failed","value":{"ok":false,"error":{"code":"revoke_failed","message":"The OAuth connection could not be revoked."}}}}}}},"502":{"description":"tool_failed: The upstream tool threw while executing. Reserved credits are refunded automatically. → Retry with backoff; if it persists the integration is down — check status and report.\noauth_callback_failed: The OAuth provider refused the code exchange or the profile lookup. → Restart the connect flow; if it persists the provider app credentials may be misconfigured.\noauth_provider_not_configured: The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY. → The workspace owner should contact support; agents cannot fix this themselves.","content":{"application/json":{"examples":{"tool_failed":{"summary":"tool_failed","value":{"ok":false,"error":{"code":"tool_failed","message":"The upstream tool threw while executing. Reserved credits are refunded automatically."}}},"oauth_callback_failed":{"summary":"oauth_callback_failed","value":{"ok":false,"error":{"code":"oauth_callback_failed","message":"The OAuth provider refused the code exchange or the profile lookup."}}},"oauth_provider_not_configured":{"summary":"oauth_provider_not_configured","value":{"ok":false,"error":{"code":"oauth_provider_not_configured","message":"The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY."}}}}}}},"503":{"description":"metering_unavailable: Credit metering could not be reached, so the call was not authorized or charged. → Retry with backoff; the same idempotency-key is safe to reuse.","content":{"application/json":{"examples":{"metering_unavailable":{"summary":"metering_unavailable","value":{"ok":false,"error":{"code":"metering_unavailable","message":"Credit metering could not be reached, so the call was not authorized or charged."}}}}}}}}}},"/api/public/v1/tools/sandbox_list_records":{"post":{"operationId":"sandbox_list_records","summary":"List records (sandbox)","description":"Sandbox: lists fixture records (contacts, invoices, tickets) with paging and filtering. Free — no real data. Costs 0 credit(s).","security":[{"agentKey":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Replay-safe key scoped to your API key. A repeated completed call returns the stored response and is not charged again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Record type: contacts, invoices or tickets"},"status":{"type":"string","description":"Optional status filter; omit for all records"},"limit":{"type":"number","description":"Page size, 1-100. Defaults to 25"},"cursor":{"type":"string","description":"Opaque cursor from a previous nextCursor"}},"required":["type"],"additionalProperties":false},"examples":{"default":{"summary":"Example call","value":{"type":"invoices","limit":25}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"examples":{"default":{"summary":"Success","value":{"ok":true,"requestId":"b0e1c8a2-9f4d-4d0f-9a1e-2c5d7f8e1a30","tool":"sandbox_list_records","demo":true,"credits":{"charged":0,"balance":500},"result":{"ok":true,"type":"invoices","count":2,"rows":[{"id":"in_881","contact":"dana@northwind.io","amountCents":420000,"status":"paid"},{"id":"in_882","contact":"priya@fernbrook.co","amountCents":89000,"status":"open"}],"nextCursor":null}}}}}}},"401":{"description":"missing_api_key: No Authorization: Bearer header on the request. → Send Authorization: Bearer sk_agent_… , or POST /api/public/v1/signup to mint a key.\ninvalid_api_key: The key is unknown, revoked, or past its rotation grace window. → Rotate with POST /api/public/v1/keys/rotate, or create a new key in the console.\nkey_expired: The key passed the expiry date set by its owner. → Rotate the key or issue a new one in the console.","content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"ok":false,"error":{"code":"missing_api_key","message":"No Authorization: Bearer header on the request."}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"ok":false,"error":{"code":"invalid_api_key","message":"The key is unknown, revoked, or past its rotation grace window."}}},"key_expired":{"summary":"key_expired","value":{"ok":false,"error":{"code":"key_expired","message":"The key passed the expiry date set by its owner."}}}}}}},"402":{"description":"insufficient_credits: The workspace balance is below this tool's price. Nothing was executed or charged. → Pay machine-to-machine: the body carries an x402 accepts[] offer — settle it and retry the same request with an X-PAYMENT header. Humans can instead buy credits via POST /api/public/v1/claim.\npayment_failed: An X-PAYMENT header was supplied but the facilitator could not verify or settle it. → Re-read accepts[0] from a fresh 402, rebuild the payment payload for the exact amount, asset and network, and retry.","content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"ok":false,"error":{"code":"insufficient_credits","message":"The workspace balance is below this tool's price. Nothing was executed or charged.","required":5,"balance":2}}},"payment_failed":{"summary":"payment_failed","value":{"ok":false,"error":{"code":"payment_failed","message":"An X-PAYMENT header was supplied but the facilitator could not verify or settle it."}}}}}}},"403":{"description":"budget_exceeded: The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key. → Wait for the window to roll over, or ask the key owner to raise the cap in the console.\ntool_not_allowed: This key has a tool allowlist that does not include the requested tool. → Call an allowed tool, or ask the key owner to widen the allowlist.\ntool_disabled: The workspace owner has disabled this tool for the org. → Enable the tool in the console, or call a different tool.\ninsufficient_scope: The key is valid but does not carry the tools:invoke scope. → Issue a key with tools:invoke from the console and retry with it.","content":{"application/json":{"examples":{"budget_exceeded":{"summary":"budget_exceeded","value":{"ok":false,"error":{"code":"budget_exceeded","message":"The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key."}}},"tool_not_allowed":{"summary":"tool_not_allowed","value":{"ok":false,"error":{"code":"tool_not_allowed","message":"This key has a tool allowlist that does not include the requested tool."}}},"tool_disabled":{"summary":"tool_disabled","value":{"ok":false,"error":{"code":"tool_disabled","message":"The workspace owner has disabled this tool for the org."}}},"insufficient_scope":{"summary":"insufficient_scope","value":{"ok":false,"error":{"code":"insufficient_scope","message":"The key is valid but does not carry the tools:invoke scope."}}}}}}},"404":{"description":"unknown_tool: No public tool with that name exists in the catalog. → Re-read GET /api/public/v1/tools and use an exact name from the catalog.\napproval_intent_not_found: No approval intent with that id exists in this workspace. → Use the intent_id from the 428 approval object; intents expire after 24 hours.\noauth_provider_unknown: No OAuth provider with that slug is enabled. → GET /api/public/v1/oauth/providers for the supported catalog.\nconnection_not_found: No OAuth connection with that id exists in this workspace. → List connections with GET /api/public/v1/oauth/connections and use a current id.","content":{"application/json":{"examples":{"unknown_tool":{"summary":"unknown_tool","value":{"ok":false,"error":{"code":"unknown_tool","message":"No public tool with that name exists in the catalog."}}},"approval_intent_not_found":{"summary":"approval_intent_not_found","value":{"ok":false,"error":{"code":"approval_intent_not_found","message":"No approval intent with that id exists in this workspace."}}},"oauth_provider_unknown":{"summary":"oauth_provider_unknown","value":{"ok":false,"error":{"code":"oauth_provider_unknown","message":"No OAuth provider with that slug is enabled."}}},"connection_not_found":{"summary":"connection_not_found","value":{"ok":false,"error":{"code":"connection_not_found","message":"No OAuth connection with that id exists in this workspace."}}}}}}},"409":{"description":"request_in_progress: Another call with the same idempotency-key is still executing, or an approved confirmation token is already running. → Wait and retry the same idempotency-key to receive the stored response; do not change the body. If the original request is known to have failed, retry with a new idempotency-key. For a confirmation token, call the tool again with no token to get a fresh preview.\noauth_connection_required: This tool needs a connected third-party account, and none is linked for this workspace. → POST the connect URL from the body with your API key to get an authorization URL, have your operator complete the OAuth flow, then retry the call.","content":{"application/json":{"examples":{"request_in_progress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"Another call with the same idempotency-key is still executing, or an approved confirmation token is already running."}}},"oauth_connection_required":{"summary":"oauth_connection_required","value":{"ok":false,"error":{"code":"oauth_connection_required","message":"This tool needs a connected third-party account, and none is linked for this workspace."}}}}}}},"422":{"description":"invalid_json: The request body was not valid JSON. → Send a JSON object with content-type: application/json.\ninvalid_input: Arguments failed the tool's JSON Schema. No credits were charged. → Fix the fields listed in error.issues[].path and resend.","content":{"application/json":{"examples":{"invalid_json":{"summary":"invalid_json","value":{"ok":false,"error":{"code":"invalid_json","message":"The request body was not valid JSON."}}},"invalid_input":{"summary":"invalid_input","value":{"ok":false,"error":{"code":"invalid_input","message":"Arguments failed the tool's JSON Schema. No credits were charged."}}}}}}},"429":{"description":"rate_limited: Over 60 calls per minute for this API key. → Back off ~1 minute, or mint additional keys for parallel workers.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Over 60 calls per minute for this API key."}}}}}}},"500":{"description":"oauth_authorize_failed: The OAuth authorization URL could not be generated. → Retry; if it persists, check that the provider is still enabled.\ncatalog_unavailable: The OAuth provider catalog could not be loaded. → Retry shortly.\nconnections_unavailable: The workspace's OAuth connections could not be listed. → Retry shortly.\nrevoke_failed: The OAuth connection could not be revoked. → Retry; the connection remains active until revocation succeeds.","content":{"application/json":{"examples":{"oauth_authorize_failed":{"summary":"oauth_authorize_failed","value":{"ok":false,"error":{"code":"oauth_authorize_failed","message":"The OAuth authorization URL could not be generated."}}},"catalog_unavailable":{"summary":"catalog_unavailable","value":{"ok":false,"error":{"code":"catalog_unavailable","message":"The OAuth provider catalog could not be loaded."}}},"connections_unavailable":{"summary":"connections_unavailable","value":{"ok":false,"error":{"code":"connections_unavailable","message":"The workspace's OAuth connections could not be listed."}}},"revoke_failed":{"summary":"revoke_failed","value":{"ok":false,"error":{"code":"revoke_failed","message":"The OAuth connection could not be revoked."}}}}}}},"502":{"description":"tool_failed: The upstream tool threw while executing. Reserved credits are refunded automatically. → Retry with backoff; if it persists the integration is down — check status and report.\noauth_callback_failed: The OAuth provider refused the code exchange or the profile lookup. → Restart the connect flow; if it persists the provider app credentials may be misconfigured.\noauth_provider_not_configured: The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY. → The workspace owner should contact support; agents cannot fix this themselves.","content":{"application/json":{"examples":{"tool_failed":{"summary":"tool_failed","value":{"ok":false,"error":{"code":"tool_failed","message":"The upstream tool threw while executing. Reserved credits are refunded automatically."}}},"oauth_callback_failed":{"summary":"oauth_callback_failed","value":{"ok":false,"error":{"code":"oauth_callback_failed","message":"The OAuth provider refused the code exchange or the profile lookup."}}},"oauth_provider_not_configured":{"summary":"oauth_provider_not_configured","value":{"ok":false,"error":{"code":"oauth_provider_not_configured","message":"The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY."}}}}}}},"503":{"description":"metering_unavailable: Credit metering could not be reached, so the call was not authorized or charged. → Retry with backoff; the same idempotency-key is safe to reuse.","content":{"application/json":{"examples":{"metering_unavailable":{"summary":"metering_unavailable","value":{"ok":false,"error":{"code":"metering_unavailable","message":"Credit metering could not be reached, so the call was not authorized or charged."}}}}}}}}}},"/api/public/v1/tools/sandbox_send_email":{"post":{"operationId":"sandbox_send_email","summary":"Send email (sandbox)","description":"Sandbox: simulates sending an email and returns a fake message id. Nothing is delivered. Free, and still side-effecting so you can exercise the confirmation flow. Costs 0 credit(s). Side-effecting: the first call returns 428 confirmation_required with a preview and a single-use confirmationToken; resend the identical body with header x-confirmation-token to execute.","security":[{"agentKey":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Replay-safe key scoped to your API key. A repeated completed call returns the stored response and is not charged again."},{"name":"x-confirmation-token","in":"header","required":false,"schema":{"type":"string"},"description":"Single-use token from a prior 428 confirmation_required response, bound to this exact request body. Omit it on the first call to receive the preview and token."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","description":"Recipient email address"},"subject":{"type":"string","description":"Email subject"},"body":{"type":"string","description":"Plain text email body"}},"required":["to","subject","body"],"additionalProperties":false},"examples":{"default":{"summary":"Example call","value":{"to":"dana@northwind.io","subject":"Your invoice is ready","body":"Hi Dana — invoice in_881 is attached. Thanks!"}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"examples":{"default":{"summary":"Success","value":{"ok":true,"requestId":"b0e1c8a2-9f4d-4d0f-9a1e-2c5d7f8e1a30","tool":"sandbox_send_email","demo":true,"credits":{"charged":0,"balance":500},"result":{"ok":true,"simulated":true,"messageId":"sim_4f2a91cd","to":"dana@northwind.io","subject":"Your invoice is ready","deliveredAt":"2026-08-09T20:15:18.358Z"}}}}}}},"401":{"description":"missing_api_key: No Authorization: Bearer header on the request. → Send Authorization: Bearer sk_agent_… , or POST /api/public/v1/signup to mint a key.\ninvalid_api_key: The key is unknown, revoked, or past its rotation grace window. → Rotate with POST /api/public/v1/keys/rotate, or create a new key in the console.\nkey_expired: The key passed the expiry date set by its owner. → Rotate the key or issue a new one in the console.","content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"ok":false,"error":{"code":"missing_api_key","message":"No Authorization: Bearer header on the request."}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"ok":false,"error":{"code":"invalid_api_key","message":"The key is unknown, revoked, or past its rotation grace window."}}},"key_expired":{"summary":"key_expired","value":{"ok":false,"error":{"code":"key_expired","message":"The key passed the expiry date set by its owner."}}}}}}},"402":{"description":"insufficient_credits: The workspace balance is below this tool's price. Nothing was executed or charged. → Pay machine-to-machine: the body carries an x402 accepts[] offer — settle it and retry the same request with an X-PAYMENT header. Humans can instead buy credits via POST /api/public/v1/claim.\npayment_failed: An X-PAYMENT header was supplied but the facilitator could not verify or settle it. → Re-read accepts[0] from a fresh 402, rebuild the payment payload for the exact amount, asset and network, and retry.","content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"ok":false,"error":{"code":"insufficient_credits","message":"The workspace balance is below this tool's price. Nothing was executed or charged.","required":5,"balance":2}}},"payment_failed":{"summary":"payment_failed","value":{"ok":false,"error":{"code":"payment_failed","message":"An X-PAYMENT header was supplied but the facilitator could not verify or settle it."}}}}}}},"403":{"description":"budget_exceeded: The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key. → Wait for the window to roll over, or ask the key owner to raise the cap in the console.\ntool_not_allowed: This key has a tool allowlist that does not include the requested tool. → Call an allowed tool, or ask the key owner to widen the allowlist.\ntool_disabled: The workspace owner has disabled this tool for the org. → Enable the tool in the console, or call a different tool.\ninsufficient_scope: The key is valid but does not carry the tools:invoke scope. → Issue a key with tools:invoke from the console and retry with it.\nconfirmation_invalid: The x-confirmation-token header is unknown or belongs to another workspace. → Call the tool without a token to receive a fresh preview and token, then retry.","content":{"application/json":{"examples":{"budget_exceeded":{"summary":"budget_exceeded","value":{"ok":false,"error":{"code":"budget_exceeded","message":"The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key."}}},"tool_not_allowed":{"summary":"tool_not_allowed","value":{"ok":false,"error":{"code":"tool_not_allowed","message":"This key has a tool allowlist that does not include the requested tool."}}},"tool_disabled":{"summary":"tool_disabled","value":{"ok":false,"error":{"code":"tool_disabled","message":"The workspace owner has disabled this tool for the org."}}},"insufficient_scope":{"summary":"insufficient_scope","value":{"ok":false,"error":{"code":"insufficient_scope","message":"The key is valid but does not carry the tools:invoke scope."}}},"confirmation_invalid":{"summary":"confirmation_invalid","value":{"ok":false,"error":{"code":"confirmation_invalid","message":"The x-confirmation-token header is unknown or belongs to another workspace."}}}}}}},"404":{"description":"unknown_tool: No public tool with that name exists in the catalog. → Re-read GET /api/public/v1/tools and use an exact name from the catalog.\napproval_intent_not_found: No approval intent with that id exists in this workspace. → Use the intent_id from the 428 approval object; intents expire after 24 hours.\noauth_provider_unknown: No OAuth provider with that slug is enabled. → GET /api/public/v1/oauth/providers for the supported catalog.\nconnection_not_found: No OAuth connection with that id exists in this workspace. → List connections with GET /api/public/v1/oauth/connections and use a current id.","content":{"application/json":{"examples":{"unknown_tool":{"summary":"unknown_tool","value":{"ok":false,"error":{"code":"unknown_tool","message":"No public tool with that name exists in the catalog."}}},"approval_intent_not_found":{"summary":"approval_intent_not_found","value":{"ok":false,"error":{"code":"approval_intent_not_found","message":"No approval intent with that id exists in this workspace."}}},"oauth_provider_unknown":{"summary":"oauth_provider_unknown","value":{"ok":false,"error":{"code":"oauth_provider_unknown","message":"No OAuth provider with that slug is enabled."}}},"connection_not_found":{"summary":"connection_not_found","value":{"ok":false,"error":{"code":"connection_not_found","message":"No OAuth connection with that id exists in this workspace."}}}}}}},"409":{"description":"request_in_progress: Another call with the same idempotency-key is still executing, or an approved confirmation token is already running. → Wait and retry the same idempotency-key to receive the stored response; do not change the body. If the original request is known to have failed, retry with a new idempotency-key. For a confirmation token, call the tool again with no token to get a fresh preview.\nconfirmation_mismatch: The token is bound to a specific tool and argument set; this request differs from what was previewed. → Send the exact body that was previewed, or request a new confirmation for the new body.\nconfirmation_used: That confirmation token was already redeemed. Tokens are single-use. → Request a new confirmation for the next call.\noauth_connection_required: This tool needs a connected third-party account, and none is linked for this workspace. → POST the connect URL from the body with your API key to get an authorization URL, have your operator complete the OAuth flow, then retry the call.","content":{"application/json":{"examples":{"request_in_progress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"Another call with the same idempotency-key is still executing, or an approved confirmation token is already running."}}},"confirmation_mismatch":{"summary":"confirmation_mismatch","value":{"ok":false,"error":{"code":"confirmation_mismatch","message":"The token is bound to a specific tool and argument set; this request differs from what was previewed."}}},"confirmation_used":{"summary":"confirmation_used","value":{"ok":false,"error":{"code":"confirmation_used","message":"That confirmation token was already redeemed. Tokens are single-use."}}},"oauth_connection_required":{"summary":"oauth_connection_required","value":{"ok":false,"error":{"code":"oauth_connection_required","message":"This tool needs a connected third-party account, and none is linked for this workspace."}}}}}}},"410":{"description":"confirmation_expired: The confirmation token passed its 10-minute validity window. → Call again without a token to get a new preview and token.","content":{"application/json":{"examples":{"confirmation_expired":{"summary":"confirmation_expired","value":{"ok":false,"error":{"code":"confirmation_expired","message":"The confirmation token passed its 10-minute validity window."}}}}}}},"422":{"description":"invalid_json: The request body was not valid JSON. → Send a JSON object with content-type: application/json.\ninvalid_input: Arguments failed the tool's JSON Schema. No credits were charged. → Fix the fields listed in error.issues[].path and resend.","content":{"application/json":{"examples":{"invalid_json":{"summary":"invalid_json","value":{"ok":false,"error":{"code":"invalid_json","message":"The request body was not valid JSON."}}},"invalid_input":{"summary":"invalid_input","value":{"ok":false,"error":{"code":"invalid_input","message":"Arguments failed the tool's JSON Schema. No credits were charged."}}}}}}},"428":{"description":"confirmation_required: A side-effecting tool was called without a confirmation token. Nothing was executed or charged. → Show error.preview to your operator. Once they approve, repeat the identical request with header x-confirmation-token: <error.confirmationToken>.","content":{"application/json":{"examples":{"confirmation_required":{"summary":"confirmation_required","value":{"ok":false,"error":{"code":"confirmation_required","message":"A side-effecting tool was called without a confirmation token. Nothing was executed or charged."}}}}}}},"429":{"description":"rate_limited: Over 60 calls per minute for this API key. → Back off ~1 minute, or mint additional keys for parallel workers.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Over 60 calls per minute for this API key."}}}}}}},"500":{"description":"oauth_authorize_failed: The OAuth authorization URL could not be generated. → Retry; if it persists, check that the provider is still enabled.\ncatalog_unavailable: The OAuth provider catalog could not be loaded. → Retry shortly.\nconnections_unavailable: The workspace's OAuth connections could not be listed. → Retry shortly.\nrevoke_failed: The OAuth connection could not be revoked. → Retry; the connection remains active until revocation succeeds.","content":{"application/json":{"examples":{"oauth_authorize_failed":{"summary":"oauth_authorize_failed","value":{"ok":false,"error":{"code":"oauth_authorize_failed","message":"The OAuth authorization URL could not be generated."}}},"catalog_unavailable":{"summary":"catalog_unavailable","value":{"ok":false,"error":{"code":"catalog_unavailable","message":"The OAuth provider catalog could not be loaded."}}},"connections_unavailable":{"summary":"connections_unavailable","value":{"ok":false,"error":{"code":"connections_unavailable","message":"The workspace's OAuth connections could not be listed."}}},"revoke_failed":{"summary":"revoke_failed","value":{"ok":false,"error":{"code":"revoke_failed","message":"The OAuth connection could not be revoked."}}}}}}},"502":{"description":"tool_failed: The upstream tool threw while executing. Reserved credits are refunded automatically. → Retry with backoff; if it persists the integration is down — check status and report.\noauth_callback_failed: The OAuth provider refused the code exchange or the profile lookup. → Restart the connect flow; if it persists the provider app credentials may be misconfigured.\noauth_provider_not_configured: The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY. → The workspace owner should contact support; agents cannot fix this themselves.","content":{"application/json":{"examples":{"tool_failed":{"summary":"tool_failed","value":{"ok":false,"error":{"code":"tool_failed","message":"The upstream tool threw while executing. Reserved credits are refunded automatically."}}},"oauth_callback_failed":{"summary":"oauth_callback_failed","value":{"ok":false,"error":{"code":"oauth_callback_failed","message":"The OAuth provider refused the code exchange or the profile lookup."}}},"oauth_provider_not_configured":{"summary":"oauth_provider_not_configured","value":{"ok":false,"error":{"code":"oauth_provider_not_configured","message":"The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY."}}}}}}},"503":{"description":"metering_unavailable: Credit metering could not be reached, so the call was not authorized or charged. → Retry with backoff; the same idempotency-key is safe to reuse.","content":{"application/json":{"examples":{"metering_unavailable":{"summary":"metering_unavailable","value":{"ok":false,"error":{"code":"metering_unavailable","message":"Credit metering could not be reached, so the call was not authorized or charged."}}}}}}}}}},"/api/public/v1/tools/sandbox_update_crm_record":{"post":{"operationId":"sandbox_update_crm_record","summary":"Update CRM record (sandbox)","description":"Sandbox: simulates updating a CRM record. Nothing is written. Free, and still side-effecting so you can exercise the confirmation flow. Costs 0 credit(s). Side-effecting: the first call returns 428 confirmation_required with a preview and a single-use confirmationToken; resend the identical body with header x-confirmation-token to execute.","security":[{"agentKey":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Replay-safe key scoped to your API key. A repeated completed call returns the stored response and is not charged again."},{"name":"x-confirmation-token","in":"header","required":false,"schema":{"type":"string"},"description":"Single-use token from a prior 428 confirmation_required response, bound to this exact request body. Omit it on the first call to receive the preview and token."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"recordId":{"type":"string","description":"CRM record id"},"fields":{"type":"object","additionalProperties":{},"description":"Object of field names to new values, e.g. { stage: \"churn_risk\" }"}},"required":["recordId","fields"],"additionalProperties":false},"examples":{"default":{"summary":"Example call","value":{"recordId":"c_1024","fields":{"stage":"churn_risk","owner":"ae_12"}}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"examples":{"default":{"summary":"Success","value":{"ok":true,"requestId":"b0e1c8a2-9f4d-4d0f-9a1e-2c5d7f8e1a30","tool":"sandbox_update_crm_record","demo":true,"credits":{"charged":0,"balance":500},"result":{"ok":true,"simulated":true,"recordId":"c_1024","updatedFields":{"stage":"churn_risk","owner":"ae_12"},"updatedAt":"2026-08-09T20:15:18.358Z"}}}}}}},"401":{"description":"missing_api_key: No Authorization: Bearer header on the request. → Send Authorization: Bearer sk_agent_… , or POST /api/public/v1/signup to mint a key.\ninvalid_api_key: The key is unknown, revoked, or past its rotation grace window. → Rotate with POST /api/public/v1/keys/rotate, or create a new key in the console.\nkey_expired: The key passed the expiry date set by its owner. → Rotate the key or issue a new one in the console.","content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"ok":false,"error":{"code":"missing_api_key","message":"No Authorization: Bearer header on the request."}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"ok":false,"error":{"code":"invalid_api_key","message":"The key is unknown, revoked, or past its rotation grace window."}}},"key_expired":{"summary":"key_expired","value":{"ok":false,"error":{"code":"key_expired","message":"The key passed the expiry date set by its owner."}}}}}}},"402":{"description":"insufficient_credits: The workspace balance is below this tool's price. Nothing was executed or charged. → Pay machine-to-machine: the body carries an x402 accepts[] offer — settle it and retry the same request with an X-PAYMENT header. Humans can instead buy credits via POST /api/public/v1/claim.\npayment_failed: An X-PAYMENT header was supplied but the facilitator could not verify or settle it. → Re-read accepts[0] from a fresh 402, rebuild the payment payload for the exact amount, asset and network, and retry.","content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"ok":false,"error":{"code":"insufficient_credits","message":"The workspace balance is below this tool's price. Nothing was executed or charged.","required":5,"balance":2}}},"payment_failed":{"summary":"payment_failed","value":{"ok":false,"error":{"code":"payment_failed","message":"An X-PAYMENT header was supplied but the facilitator could not verify or settle it."}}}}}}},"403":{"description":"budget_exceeded: The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key. → Wait for the window to roll over, or ask the key owner to raise the cap in the console.\ntool_not_allowed: This key has a tool allowlist that does not include the requested tool. → Call an allowed tool, or ask the key owner to widen the allowlist.\ntool_disabled: The workspace owner has disabled this tool for the org. → Enable the tool in the console, or call a different tool.\ninsufficient_scope: The key is valid but does not carry the tools:invoke scope. → Issue a key with tools:invoke from the console and retry with it.\nconfirmation_invalid: The x-confirmation-token header is unknown or belongs to another workspace. → Call the tool without a token to receive a fresh preview and token, then retry.","content":{"application/json":{"examples":{"budget_exceeded":{"summary":"budget_exceeded","value":{"ok":false,"error":{"code":"budget_exceeded","message":"The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key."}}},"tool_not_allowed":{"summary":"tool_not_allowed","value":{"ok":false,"error":{"code":"tool_not_allowed","message":"This key has a tool allowlist that does not include the requested tool."}}},"tool_disabled":{"summary":"tool_disabled","value":{"ok":false,"error":{"code":"tool_disabled","message":"The workspace owner has disabled this tool for the org."}}},"insufficient_scope":{"summary":"insufficient_scope","value":{"ok":false,"error":{"code":"insufficient_scope","message":"The key is valid but does not carry the tools:invoke scope."}}},"confirmation_invalid":{"summary":"confirmation_invalid","value":{"ok":false,"error":{"code":"confirmation_invalid","message":"The x-confirmation-token header is unknown or belongs to another workspace."}}}}}}},"404":{"description":"unknown_tool: No public tool with that name exists in the catalog. → Re-read GET /api/public/v1/tools and use an exact name from the catalog.\napproval_intent_not_found: No approval intent with that id exists in this workspace. → Use the intent_id from the 428 approval object; intents expire after 24 hours.\noauth_provider_unknown: No OAuth provider with that slug is enabled. → GET /api/public/v1/oauth/providers for the supported catalog.\nconnection_not_found: No OAuth connection with that id exists in this workspace. → List connections with GET /api/public/v1/oauth/connections and use a current id.","content":{"application/json":{"examples":{"unknown_tool":{"summary":"unknown_tool","value":{"ok":false,"error":{"code":"unknown_tool","message":"No public tool with that name exists in the catalog."}}},"approval_intent_not_found":{"summary":"approval_intent_not_found","value":{"ok":false,"error":{"code":"approval_intent_not_found","message":"No approval intent with that id exists in this workspace."}}},"oauth_provider_unknown":{"summary":"oauth_provider_unknown","value":{"ok":false,"error":{"code":"oauth_provider_unknown","message":"No OAuth provider with that slug is enabled."}}},"connection_not_found":{"summary":"connection_not_found","value":{"ok":false,"error":{"code":"connection_not_found","message":"No OAuth connection with that id exists in this workspace."}}}}}}},"409":{"description":"request_in_progress: Another call with the same idempotency-key is still executing, or an approved confirmation token is already running. → Wait and retry the same idempotency-key to receive the stored response; do not change the body. If the original request is known to have failed, retry with a new idempotency-key. For a confirmation token, call the tool again with no token to get a fresh preview.\nconfirmation_mismatch: The token is bound to a specific tool and argument set; this request differs from what was previewed. → Send the exact body that was previewed, or request a new confirmation for the new body.\nconfirmation_used: That confirmation token was already redeemed. Tokens are single-use. → Request a new confirmation for the next call.\noauth_connection_required: This tool needs a connected third-party account, and none is linked for this workspace. → POST the connect URL from the body with your API key to get an authorization URL, have your operator complete the OAuth flow, then retry the call.","content":{"application/json":{"examples":{"request_in_progress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"Another call with the same idempotency-key is still executing, or an approved confirmation token is already running."}}},"confirmation_mismatch":{"summary":"confirmation_mismatch","value":{"ok":false,"error":{"code":"confirmation_mismatch","message":"The token is bound to a specific tool and argument set; this request differs from what was previewed."}}},"confirmation_used":{"summary":"confirmation_used","value":{"ok":false,"error":{"code":"confirmation_used","message":"That confirmation token was already redeemed. Tokens are single-use."}}},"oauth_connection_required":{"summary":"oauth_connection_required","value":{"ok":false,"error":{"code":"oauth_connection_required","message":"This tool needs a connected third-party account, and none is linked for this workspace."}}}}}}},"410":{"description":"confirmation_expired: The confirmation token passed its 10-minute validity window. → Call again without a token to get a new preview and token.","content":{"application/json":{"examples":{"confirmation_expired":{"summary":"confirmation_expired","value":{"ok":false,"error":{"code":"confirmation_expired","message":"The confirmation token passed its 10-minute validity window."}}}}}}},"422":{"description":"invalid_json: The request body was not valid JSON. → Send a JSON object with content-type: application/json.\ninvalid_input: Arguments failed the tool's JSON Schema. No credits were charged. → Fix the fields listed in error.issues[].path and resend.","content":{"application/json":{"examples":{"invalid_json":{"summary":"invalid_json","value":{"ok":false,"error":{"code":"invalid_json","message":"The request body was not valid JSON."}}},"invalid_input":{"summary":"invalid_input","value":{"ok":false,"error":{"code":"invalid_input","message":"Arguments failed the tool's JSON Schema. No credits were charged."}}}}}}},"428":{"description":"confirmation_required: A side-effecting tool was called without a confirmation token. Nothing was executed or charged. → Show error.preview to your operator. Once they approve, repeat the identical request with header x-confirmation-token: <error.confirmationToken>.","content":{"application/json":{"examples":{"confirmation_required":{"summary":"confirmation_required","value":{"ok":false,"error":{"code":"confirmation_required","message":"A side-effecting tool was called without a confirmation token. Nothing was executed or charged."}}}}}}},"429":{"description":"rate_limited: Over 60 calls per minute for this API key. → Back off ~1 minute, or mint additional keys for parallel workers.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Over 60 calls per minute for this API key."}}}}}}},"500":{"description":"oauth_authorize_failed: The OAuth authorization URL could not be generated. → Retry; if it persists, check that the provider is still enabled.\ncatalog_unavailable: The OAuth provider catalog could not be loaded. → Retry shortly.\nconnections_unavailable: The workspace's OAuth connections could not be listed. → Retry shortly.\nrevoke_failed: The OAuth connection could not be revoked. → Retry; the connection remains active until revocation succeeds.","content":{"application/json":{"examples":{"oauth_authorize_failed":{"summary":"oauth_authorize_failed","value":{"ok":false,"error":{"code":"oauth_authorize_failed","message":"The OAuth authorization URL could not be generated."}}},"catalog_unavailable":{"summary":"catalog_unavailable","value":{"ok":false,"error":{"code":"catalog_unavailable","message":"The OAuth provider catalog could not be loaded."}}},"connections_unavailable":{"summary":"connections_unavailable","value":{"ok":false,"error":{"code":"connections_unavailable","message":"The workspace's OAuth connections could not be listed."}}},"revoke_failed":{"summary":"revoke_failed","value":{"ok":false,"error":{"code":"revoke_failed","message":"The OAuth connection could not be revoked."}}}}}}},"502":{"description":"tool_failed: The upstream tool threw while executing. Reserved credits are refunded automatically. → Retry with backoff; if it persists the integration is down — check status and report.\noauth_callback_failed: The OAuth provider refused the code exchange or the profile lookup. → Restart the connect flow; if it persists the provider app credentials may be misconfigured.\noauth_provider_not_configured: The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY. → The workspace owner should contact support; agents cannot fix this themselves.","content":{"application/json":{"examples":{"tool_failed":{"summary":"tool_failed","value":{"ok":false,"error":{"code":"tool_failed","message":"The upstream tool threw while executing. Reserved credits are refunded automatically."}}},"oauth_callback_failed":{"summary":"oauth_callback_failed","value":{"ok":false,"error":{"code":"oauth_callback_failed","message":"The OAuth provider refused the code exchange or the profile lookup."}}},"oauth_provider_not_configured":{"summary":"oauth_provider_not_configured","value":{"ok":false,"error":{"code":"oauth_provider_not_configured","message":"The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY."}}}}}}},"503":{"description":"metering_unavailable: Credit metering could not be reached, so the call was not authorized or charged. → Retry with backoff; the same idempotency-key is safe to reuse.","content":{"application/json":{"examples":{"metering_unavailable":{"summary":"metering_unavailable","value":{"ok":false,"error":{"code":"metering_unavailable","message":"Credit metering could not be reached, so the call was not authorized or charged."}}}}}}}}}},"/api/public/v1/tools/sandbox_create_payment":{"post":{"operationId":"sandbox_create_payment","summary":"Create payment (sandbox)","description":"Sandbox: simulates creating a payment charge. No money moves. Free, and still side-effecting so you can exercise the confirmation flow. Costs 0 credit(s). Side-effecting: the first call returns 428 confirmation_required with a preview and a single-use confirmationToken; resend the identical body with header x-confirmation-token to execute.","security":[{"agentKey":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Replay-safe key scoped to your API key. A repeated completed call returns the stored response and is not charged again."},{"name":"x-confirmation-token","in":"header","required":false,"schema":{"type":"string"},"description":"Single-use token from a prior 428 confirmation_required response, bound to this exact request body. Omit it on the first call to receive the preview and token."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","description":"Customer id"},"amountCents":{"type":"number","description":"Amount in cents"},"currency":{"type":"string","description":"ISO currency code, e.g. usd"}},"required":["customerId","amountCents","currency"],"additionalProperties":false},"examples":{"default":{"summary":"Example call","value":{"customerId":"c_1024","amountCents":4200,"currency":"usd"}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"examples":{"default":{"summary":"Success","value":{"ok":true,"requestId":"b0e1c8a2-9f4d-4d0f-9a1e-2c5d7f8e1a30","tool":"sandbox_create_payment","demo":true,"credits":{"charged":0,"balance":500},"result":{"ok":true,"simulated":true,"paymentId":"pay_9c31be40","customerId":"c_1024","amountCents":4200,"currency":"usd","status":"succeeded"}}}}}}},"401":{"description":"missing_api_key: No Authorization: Bearer header on the request. → Send Authorization: Bearer sk_agent_… , or POST /api/public/v1/signup to mint a key.\ninvalid_api_key: The key is unknown, revoked, or past its rotation grace window. → Rotate with POST /api/public/v1/keys/rotate, or create a new key in the console.\nkey_expired: The key passed the expiry date set by its owner. → Rotate the key or issue a new one in the console.","content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"ok":false,"error":{"code":"missing_api_key","message":"No Authorization: Bearer header on the request."}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"ok":false,"error":{"code":"invalid_api_key","message":"The key is unknown, revoked, or past its rotation grace window."}}},"key_expired":{"summary":"key_expired","value":{"ok":false,"error":{"code":"key_expired","message":"The key passed the expiry date set by its owner."}}}}}}},"402":{"description":"insufficient_credits: The workspace balance is below this tool's price. Nothing was executed or charged. → Pay machine-to-machine: the body carries an x402 accepts[] offer — settle it and retry the same request with an X-PAYMENT header. Humans can instead buy credits via POST /api/public/v1/claim.\npayment_failed: An X-PAYMENT header was supplied but the facilitator could not verify or settle it. → Re-read accepts[0] from a fresh 402, rebuild the payment payload for the exact amount, asset and network, and retry.","content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"ok":false,"error":{"code":"insufficient_credits","message":"The workspace balance is below this tool's price. Nothing was executed or charged.","required":5,"balance":2}}},"payment_failed":{"summary":"payment_failed","value":{"ok":false,"error":{"code":"payment_failed","message":"An X-PAYMENT header was supplied but the facilitator could not verify or settle it."}}}}}}},"403":{"description":"budget_exceeded: The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key. → Wait for the window to roll over, or ask the key owner to raise the cap in the console.\ntool_not_allowed: This key has a tool allowlist that does not include the requested tool. → Call an allowed tool, or ask the key owner to widen the allowlist.\ntool_disabled: The workspace owner has disabled this tool for the org. → Enable the tool in the console, or call a different tool.\ninsufficient_scope: The key is valid but does not carry the tools:invoke scope. → Issue a key with tools:invoke from the console and retry with it.\nconfirmation_invalid: The x-confirmation-token header is unknown or belongs to another workspace. → Call the tool without a token to receive a fresh preview and token, then retry.","content":{"application/json":{"examples":{"budget_exceeded":{"summary":"budget_exceeded","value":{"ok":false,"error":{"code":"budget_exceeded","message":"The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key."}}},"tool_not_allowed":{"summary":"tool_not_allowed","value":{"ok":false,"error":{"code":"tool_not_allowed","message":"This key has a tool allowlist that does not include the requested tool."}}},"tool_disabled":{"summary":"tool_disabled","value":{"ok":false,"error":{"code":"tool_disabled","message":"The workspace owner has disabled this tool for the org."}}},"insufficient_scope":{"summary":"insufficient_scope","value":{"ok":false,"error":{"code":"insufficient_scope","message":"The key is valid but does not carry the tools:invoke scope."}}},"confirmation_invalid":{"summary":"confirmation_invalid","value":{"ok":false,"error":{"code":"confirmation_invalid","message":"The x-confirmation-token header is unknown or belongs to another workspace."}}}}}}},"404":{"description":"unknown_tool: No public tool with that name exists in the catalog. → Re-read GET /api/public/v1/tools and use an exact name from the catalog.\napproval_intent_not_found: No approval intent with that id exists in this workspace. → Use the intent_id from the 428 approval object; intents expire after 24 hours.\noauth_provider_unknown: No OAuth provider with that slug is enabled. → GET /api/public/v1/oauth/providers for the supported catalog.\nconnection_not_found: No OAuth connection with that id exists in this workspace. → List connections with GET /api/public/v1/oauth/connections and use a current id.","content":{"application/json":{"examples":{"unknown_tool":{"summary":"unknown_tool","value":{"ok":false,"error":{"code":"unknown_tool","message":"No public tool with that name exists in the catalog."}}},"approval_intent_not_found":{"summary":"approval_intent_not_found","value":{"ok":false,"error":{"code":"approval_intent_not_found","message":"No approval intent with that id exists in this workspace."}}},"oauth_provider_unknown":{"summary":"oauth_provider_unknown","value":{"ok":false,"error":{"code":"oauth_provider_unknown","message":"No OAuth provider with that slug is enabled."}}},"connection_not_found":{"summary":"connection_not_found","value":{"ok":false,"error":{"code":"connection_not_found","message":"No OAuth connection with that id exists in this workspace."}}}}}}},"409":{"description":"request_in_progress: Another call with the same idempotency-key is still executing, or an approved confirmation token is already running. → Wait and retry the same idempotency-key to receive the stored response; do not change the body. If the original request is known to have failed, retry with a new idempotency-key. For a confirmation token, call the tool again with no token to get a fresh preview.\nconfirmation_mismatch: The token is bound to a specific tool and argument set; this request differs from what was previewed. → Send the exact body that was previewed, or request a new confirmation for the new body.\nconfirmation_used: That confirmation token was already redeemed. Tokens are single-use. → Request a new confirmation for the next call.\noauth_connection_required: This tool needs a connected third-party account, and none is linked for this workspace. → POST the connect URL from the body with your API key to get an authorization URL, have your operator complete the OAuth flow, then retry the call.","content":{"application/json":{"examples":{"request_in_progress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"Another call with the same idempotency-key is still executing, or an approved confirmation token is already running."}}},"confirmation_mismatch":{"summary":"confirmation_mismatch","value":{"ok":false,"error":{"code":"confirmation_mismatch","message":"The token is bound to a specific tool and argument set; this request differs from what was previewed."}}},"confirmation_used":{"summary":"confirmation_used","value":{"ok":false,"error":{"code":"confirmation_used","message":"That confirmation token was already redeemed. Tokens are single-use."}}},"oauth_connection_required":{"summary":"oauth_connection_required","value":{"ok":false,"error":{"code":"oauth_connection_required","message":"This tool needs a connected third-party account, and none is linked for this workspace."}}}}}}},"410":{"description":"confirmation_expired: The confirmation token passed its 10-minute validity window. → Call again without a token to get a new preview and token.","content":{"application/json":{"examples":{"confirmation_expired":{"summary":"confirmation_expired","value":{"ok":false,"error":{"code":"confirmation_expired","message":"The confirmation token passed its 10-minute validity window."}}}}}}},"422":{"description":"invalid_json: The request body was not valid JSON. → Send a JSON object with content-type: application/json.\ninvalid_input: Arguments failed the tool's JSON Schema. No credits were charged. → Fix the fields listed in error.issues[].path and resend.","content":{"application/json":{"examples":{"invalid_json":{"summary":"invalid_json","value":{"ok":false,"error":{"code":"invalid_json","message":"The request body was not valid JSON."}}},"invalid_input":{"summary":"invalid_input","value":{"ok":false,"error":{"code":"invalid_input","message":"Arguments failed the tool's JSON Schema. No credits were charged."}}}}}}},"428":{"description":"confirmation_required: A side-effecting tool was called without a confirmation token. Nothing was executed or charged. → Show error.preview to your operator. Once they approve, repeat the identical request with header x-confirmation-token: <error.confirmationToken>.","content":{"application/json":{"examples":{"confirmation_required":{"summary":"confirmation_required","value":{"ok":false,"error":{"code":"confirmation_required","message":"A side-effecting tool was called without a confirmation token. Nothing was executed or charged."}}}}}}},"429":{"description":"rate_limited: Over 60 calls per minute for this API key. → Back off ~1 minute, or mint additional keys for parallel workers.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Over 60 calls per minute for this API key."}}}}}}},"500":{"description":"oauth_authorize_failed: The OAuth authorization URL could not be generated. → Retry; if it persists, check that the provider is still enabled.\ncatalog_unavailable: The OAuth provider catalog could not be loaded. → Retry shortly.\nconnections_unavailable: The workspace's OAuth connections could not be listed. → Retry shortly.\nrevoke_failed: The OAuth connection could not be revoked. → Retry; the connection remains active until revocation succeeds.","content":{"application/json":{"examples":{"oauth_authorize_failed":{"summary":"oauth_authorize_failed","value":{"ok":false,"error":{"code":"oauth_authorize_failed","message":"The OAuth authorization URL could not be generated."}}},"catalog_unavailable":{"summary":"catalog_unavailable","value":{"ok":false,"error":{"code":"catalog_unavailable","message":"The OAuth provider catalog could not be loaded."}}},"connections_unavailable":{"summary":"connections_unavailable","value":{"ok":false,"error":{"code":"connections_unavailable","message":"The workspace's OAuth connections could not be listed."}}},"revoke_failed":{"summary":"revoke_failed","value":{"ok":false,"error":{"code":"revoke_failed","message":"The OAuth connection could not be revoked."}}}}}}},"502":{"description":"tool_failed: The upstream tool threw while executing. Reserved credits are refunded automatically. → Retry with backoff; if it persists the integration is down — check status and report.\noauth_callback_failed: The OAuth provider refused the code exchange or the profile lookup. → Restart the connect flow; if it persists the provider app credentials may be misconfigured.\noauth_provider_not_configured: The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY. → The workspace owner should contact support; agents cannot fix this themselves.","content":{"application/json":{"examples":{"tool_failed":{"summary":"tool_failed","value":{"ok":false,"error":{"code":"tool_failed","message":"The upstream tool threw while executing. Reserved credits are refunded automatically."}}},"oauth_callback_failed":{"summary":"oauth_callback_failed","value":{"ok":false,"error":{"code":"oauth_callback_failed","message":"The OAuth provider refused the code exchange or the profile lookup."}}},"oauth_provider_not_configured":{"summary":"oauth_provider_not_configured","value":{"ok":false,"error":{"code":"oauth_provider_not_configured","message":"The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY."}}}}}}},"503":{"description":"metering_unavailable: Credit metering could not be reached, so the call was not authorized or charged. → Retry with backoff; the same idempotency-key is safe to reuse.","content":{"application/json":{"examples":{"metering_unavailable":{"summary":"metering_unavailable","value":{"ok":false,"error":{"code":"metering_unavailable","message":"Credit metering could not be reached, so the call was not authorized or charged."}}}}}}}}}},"/api/public/v1/tools/sandbox_delete_record":{"post":{"operationId":"sandbox_delete_record","summary":"Delete record (sandbox)","description":"Sandbox: simulates deleting a record. Nothing is deleted. Free, and still side-effecting so you can exercise the confirmation flow. Costs 0 credit(s). Side-effecting: the first call returns 428 confirmation_required with a preview and a single-use confirmationToken; resend the identical body with header x-confirmation-token to execute.","security":[{"agentKey":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Replay-safe key scoped to your API key. A repeated completed call returns the stored response and is not charged again."},{"name":"x-confirmation-token","in":"header","required":false,"schema":{"type":"string"},"description":"Single-use token from a prior 428 confirmation_required response, bound to this exact request body. Omit it on the first call to receive the preview and token."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Record type"},"recordId":{"type":"string","description":"Record id"}},"required":["type","recordId"],"additionalProperties":false},"examples":{"default":{"summary":"Example call","value":{"type":"tickets","recordId":"t_51"}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"examples":{"default":{"summary":"Success","value":{"ok":true,"requestId":"b0e1c8a2-9f4d-4d0f-9a1e-2c5d7f8e1a30","tool":"sandbox_delete_record","demo":true,"credits":{"charged":0,"balance":500},"result":{"ok":true,"simulated":true,"deleted":{"type":"tickets","recordId":"t_51"},"deletedAt":"2026-08-09T20:15:18.358Z"}}}}}}},"401":{"description":"missing_api_key: No Authorization: Bearer header on the request. → Send Authorization: Bearer sk_agent_… , or POST /api/public/v1/signup to mint a key.\ninvalid_api_key: The key is unknown, revoked, or past its rotation grace window. → Rotate with POST /api/public/v1/keys/rotate, or create a new key in the console.\nkey_expired: The key passed the expiry date set by its owner. → Rotate the key or issue a new one in the console.","content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"ok":false,"error":{"code":"missing_api_key","message":"No Authorization: Bearer header on the request."}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"ok":false,"error":{"code":"invalid_api_key","message":"The key is unknown, revoked, or past its rotation grace window."}}},"key_expired":{"summary":"key_expired","value":{"ok":false,"error":{"code":"key_expired","message":"The key passed the expiry date set by its owner."}}}}}}},"402":{"description":"insufficient_credits: The workspace balance is below this tool's price. Nothing was executed or charged. → Pay machine-to-machine: the body carries an x402 accepts[] offer — settle it and retry the same request with an X-PAYMENT header. Humans can instead buy credits via POST /api/public/v1/claim.\npayment_failed: An X-PAYMENT header was supplied but the facilitator could not verify or settle it. → Re-read accepts[0] from a fresh 402, rebuild the payment payload for the exact amount, asset and network, and retry.","content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"ok":false,"error":{"code":"insufficient_credits","message":"The workspace balance is below this tool's price. Nothing was executed or charged.","required":5,"balance":2}}},"payment_failed":{"summary":"payment_failed","value":{"ok":false,"error":{"code":"payment_failed","message":"An X-PAYMENT header was supplied but the facilitator could not verify or settle it."}}}}}}},"403":{"description":"budget_exceeded: The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key. → Wait for the window to roll over, or ask the key owner to raise the cap in the console.\ntool_not_allowed: This key has a tool allowlist that does not include the requested tool. → Call an allowed tool, or ask the key owner to widen the allowlist.\ntool_disabled: The workspace owner has disabled this tool for the org. → Enable the tool in the console, or call a different tool.\ninsufficient_scope: The key is valid but does not carry the tools:invoke scope. → Issue a key with tools:invoke from the console and retry with it.\nconfirmation_invalid: The x-confirmation-token header is unknown or belongs to another workspace. → Call the tool without a token to receive a fresh preview and token, then retry.","content":{"application/json":{"examples":{"budget_exceeded":{"summary":"budget_exceeded","value":{"ok":false,"error":{"code":"budget_exceeded","message":"The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key."}}},"tool_not_allowed":{"summary":"tool_not_allowed","value":{"ok":false,"error":{"code":"tool_not_allowed","message":"This key has a tool allowlist that does not include the requested tool."}}},"tool_disabled":{"summary":"tool_disabled","value":{"ok":false,"error":{"code":"tool_disabled","message":"The workspace owner has disabled this tool for the org."}}},"insufficient_scope":{"summary":"insufficient_scope","value":{"ok":false,"error":{"code":"insufficient_scope","message":"The key is valid but does not carry the tools:invoke scope."}}},"confirmation_invalid":{"summary":"confirmation_invalid","value":{"ok":false,"error":{"code":"confirmation_invalid","message":"The x-confirmation-token header is unknown or belongs to another workspace."}}}}}}},"404":{"description":"unknown_tool: No public tool with that name exists in the catalog. → Re-read GET /api/public/v1/tools and use an exact name from the catalog.\napproval_intent_not_found: No approval intent with that id exists in this workspace. → Use the intent_id from the 428 approval object; intents expire after 24 hours.\noauth_provider_unknown: No OAuth provider with that slug is enabled. → GET /api/public/v1/oauth/providers for the supported catalog.\nconnection_not_found: No OAuth connection with that id exists in this workspace. → List connections with GET /api/public/v1/oauth/connections and use a current id.","content":{"application/json":{"examples":{"unknown_tool":{"summary":"unknown_tool","value":{"ok":false,"error":{"code":"unknown_tool","message":"No public tool with that name exists in the catalog."}}},"approval_intent_not_found":{"summary":"approval_intent_not_found","value":{"ok":false,"error":{"code":"approval_intent_not_found","message":"No approval intent with that id exists in this workspace."}}},"oauth_provider_unknown":{"summary":"oauth_provider_unknown","value":{"ok":false,"error":{"code":"oauth_provider_unknown","message":"No OAuth provider with that slug is enabled."}}},"connection_not_found":{"summary":"connection_not_found","value":{"ok":false,"error":{"code":"connection_not_found","message":"No OAuth connection with that id exists in this workspace."}}}}}}},"409":{"description":"request_in_progress: Another call with the same idempotency-key is still executing, or an approved confirmation token is already running. → Wait and retry the same idempotency-key to receive the stored response; do not change the body. If the original request is known to have failed, retry with a new idempotency-key. For a confirmation token, call the tool again with no token to get a fresh preview.\nconfirmation_mismatch: The token is bound to a specific tool and argument set; this request differs from what was previewed. → Send the exact body that was previewed, or request a new confirmation for the new body.\nconfirmation_used: That confirmation token was already redeemed. Tokens are single-use. → Request a new confirmation for the next call.\noauth_connection_required: This tool needs a connected third-party account, and none is linked for this workspace. → POST the connect URL from the body with your API key to get an authorization URL, have your operator complete the OAuth flow, then retry the call.","content":{"application/json":{"examples":{"request_in_progress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"Another call with the same idempotency-key is still executing, or an approved confirmation token is already running."}}},"confirmation_mismatch":{"summary":"confirmation_mismatch","value":{"ok":false,"error":{"code":"confirmation_mismatch","message":"The token is bound to a specific tool and argument set; this request differs from what was previewed."}}},"confirmation_used":{"summary":"confirmation_used","value":{"ok":false,"error":{"code":"confirmation_used","message":"That confirmation token was already redeemed. Tokens are single-use."}}},"oauth_connection_required":{"summary":"oauth_connection_required","value":{"ok":false,"error":{"code":"oauth_connection_required","message":"This tool needs a connected third-party account, and none is linked for this workspace."}}}}}}},"410":{"description":"confirmation_expired: The confirmation token passed its 10-minute validity window. → Call again without a token to get a new preview and token.","content":{"application/json":{"examples":{"confirmation_expired":{"summary":"confirmation_expired","value":{"ok":false,"error":{"code":"confirmation_expired","message":"The confirmation token passed its 10-minute validity window."}}}}}}},"422":{"description":"invalid_json: The request body was not valid JSON. → Send a JSON object with content-type: application/json.\ninvalid_input: Arguments failed the tool's JSON Schema. No credits were charged. → Fix the fields listed in error.issues[].path and resend.","content":{"application/json":{"examples":{"invalid_json":{"summary":"invalid_json","value":{"ok":false,"error":{"code":"invalid_json","message":"The request body was not valid JSON."}}},"invalid_input":{"summary":"invalid_input","value":{"ok":false,"error":{"code":"invalid_input","message":"Arguments failed the tool's JSON Schema. No credits were charged."}}}}}}},"428":{"description":"confirmation_required: A side-effecting tool was called without a confirmation token. Nothing was executed or charged. → Show error.preview to your operator. Once they approve, repeat the identical request with header x-confirmation-token: <error.confirmationToken>.","content":{"application/json":{"examples":{"confirmation_required":{"summary":"confirmation_required","value":{"ok":false,"error":{"code":"confirmation_required","message":"A side-effecting tool was called without a confirmation token. Nothing was executed or charged."}}}}}}},"429":{"description":"rate_limited: Over 60 calls per minute for this API key. → Back off ~1 minute, or mint additional keys for parallel workers.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Over 60 calls per minute for this API key."}}}}}}},"500":{"description":"oauth_authorize_failed: The OAuth authorization URL could not be generated. → Retry; if it persists, check that the provider is still enabled.\ncatalog_unavailable: The OAuth provider catalog could not be loaded. → Retry shortly.\nconnections_unavailable: The workspace's OAuth connections could not be listed. → Retry shortly.\nrevoke_failed: The OAuth connection could not be revoked. → Retry; the connection remains active until revocation succeeds.","content":{"application/json":{"examples":{"oauth_authorize_failed":{"summary":"oauth_authorize_failed","value":{"ok":false,"error":{"code":"oauth_authorize_failed","message":"The OAuth authorization URL could not be generated."}}},"catalog_unavailable":{"summary":"catalog_unavailable","value":{"ok":false,"error":{"code":"catalog_unavailable","message":"The OAuth provider catalog could not be loaded."}}},"connections_unavailable":{"summary":"connections_unavailable","value":{"ok":false,"error":{"code":"connections_unavailable","message":"The workspace's OAuth connections could not be listed."}}},"revoke_failed":{"summary":"revoke_failed","value":{"ok":false,"error":{"code":"revoke_failed","message":"The OAuth connection could not be revoked."}}}}}}},"502":{"description":"tool_failed: The upstream tool threw while executing. Reserved credits are refunded automatically. → Retry with backoff; if it persists the integration is down — check status and report.\noauth_callback_failed: The OAuth provider refused the code exchange or the profile lookup. → Restart the connect flow; if it persists the provider app credentials may be misconfigured.\noauth_provider_not_configured: The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY. → The workspace owner should contact support; agents cannot fix this themselves.","content":{"application/json":{"examples":{"tool_failed":{"summary":"tool_failed","value":{"ok":false,"error":{"code":"tool_failed","message":"The upstream tool threw while executing. Reserved credits are refunded automatically."}}},"oauth_callback_failed":{"summary":"oauth_callback_failed","value":{"ok":false,"error":{"code":"oauth_callback_failed","message":"The OAuth provider refused the code exchange or the profile lookup."}}},"oauth_provider_not_configured":{"summary":"oauth_provider_not_configured","value":{"ok":false,"error":{"code":"oauth_provider_not_configured","message":"The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY."}}}}}}},"503":{"description":"metering_unavailable: Credit metering could not be reached, so the call was not authorized or charged. → Retry with backoff; the same idempotency-key is safe to reuse.","content":{"application/json":{"examples":{"metering_unavailable":{"summary":"metering_unavailable","value":{"ok":false,"error":{"code":"metering_unavailable","message":"Credit metering could not be reached, so the call was not authorized or charged."}}}}}}}}}},"/api/public/v1/tools/gmail_send":{"post":{"operationId":"gmail_send","summary":"Send Gmail","description":"Send an email through the workspace's connected Google account. Uses the managed OAuth connection — the agent never sees credentials. Requires the workspace to connect Google first (POST /api/public/v1/oauth/google/authorize). Side-effecting: requires confirmation. Costs 6 credit(s). Side-effecting: the first call returns 428 confirmation_required with a preview and a single-use confirmationToken; resend the identical body with header x-confirmation-token to execute.","security":[{"agentKey":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Replay-safe key scoped to your API key. A repeated completed call returns the stored response and is not charged again."},{"name":"x-confirmation-token","in":"header","required":false,"schema":{"type":"string"},"description":"Single-use token from a prior 428 confirmation_required response, bound to this exact request body. Omit it on the first call to receive the preview and token."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","description":"Recipient email address"},"subject":{"type":"string","description":"Email subject"},"body":{"type":"string","description":"Plain text email body"}},"required":["to","subject","body"],"additionalProperties":false},"examples":{"default":{"summary":"Example call","value":{"to":"dana@northwind.io","subject":"Your invoice is ready","body":"Hi Dana — invoice in_881 is attached. Thanks!"}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"examples":{"default":{"summary":"Success","value":{"ok":true,"requestId":"b0e1c8a2-9f4d-4d0f-9a1e-2c5d7f8e1a30","tool":"gmail_send","demo":false,"credits":{"charged":6,"balance":494},"result":{"ok":true,"messageId":"18f2a91cd4b5e607","to":"dana@northwind.io","threadId":"18f2a91cd4b5e607","sentAt":"2026-09-23T18:00:00.000Z"}}}}}}},"401":{"description":"missing_api_key: No Authorization: Bearer header on the request. → Send Authorization: Bearer sk_agent_… , or POST /api/public/v1/signup to mint a key.\ninvalid_api_key: The key is unknown, revoked, or past its rotation grace window. → Rotate with POST /api/public/v1/keys/rotate, or create a new key in the console.\nkey_expired: The key passed the expiry date set by its owner. → Rotate the key or issue a new one in the console.","content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"ok":false,"error":{"code":"missing_api_key","message":"No Authorization: Bearer header on the request."}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"ok":false,"error":{"code":"invalid_api_key","message":"The key is unknown, revoked, or past its rotation grace window."}}},"key_expired":{"summary":"key_expired","value":{"ok":false,"error":{"code":"key_expired","message":"The key passed the expiry date set by its owner."}}}}}}},"402":{"description":"insufficient_credits: The workspace balance is below this tool's price. Nothing was executed or charged. → Pay machine-to-machine: the body carries an x402 accepts[] offer — settle it and retry the same request with an X-PAYMENT header. Humans can instead buy credits via POST /api/public/v1/claim.\npayment_failed: An X-PAYMENT header was supplied but the facilitator could not verify or settle it. → Re-read accepts[0] from a fresh 402, rebuild the payment payload for the exact amount, asset and network, and retry.","content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"ok":false,"error":{"code":"insufficient_credits","message":"The workspace balance is below this tool's price. Nothing was executed or charged.","required":5,"balance":2}}},"payment_failed":{"summary":"payment_failed","value":{"ok":false,"error":{"code":"payment_failed","message":"An X-PAYMENT header was supplied but the facilitator could not verify or settle it."}}}}}}},"403":{"description":"budget_exceeded: The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key. → Wait for the window to roll over, or ask the key owner to raise the cap in the console.\ntool_not_allowed: This key has a tool allowlist that does not include the requested tool. → Call an allowed tool, or ask the key owner to widen the allowlist.\ntool_disabled: The workspace owner has disabled this tool for the org. → Enable the tool in the console, or call a different tool.\ninsufficient_scope: The key is valid but does not carry the tools:invoke scope. → Issue a key with tools:invoke from the console and retry with it.\nconfirmation_invalid: The x-confirmation-token header is unknown or belongs to another workspace. → Call the tool without a token to receive a fresh preview and token, then retry.","content":{"application/json":{"examples":{"budget_exceeded":{"summary":"budget_exceeded","value":{"ok":false,"error":{"code":"budget_exceeded","message":"The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key."}}},"tool_not_allowed":{"summary":"tool_not_allowed","value":{"ok":false,"error":{"code":"tool_not_allowed","message":"This key has a tool allowlist that does not include the requested tool."}}},"tool_disabled":{"summary":"tool_disabled","value":{"ok":false,"error":{"code":"tool_disabled","message":"The workspace owner has disabled this tool for the org."}}},"insufficient_scope":{"summary":"insufficient_scope","value":{"ok":false,"error":{"code":"insufficient_scope","message":"The key is valid but does not carry the tools:invoke scope."}}},"confirmation_invalid":{"summary":"confirmation_invalid","value":{"ok":false,"error":{"code":"confirmation_invalid","message":"The x-confirmation-token header is unknown or belongs to another workspace."}}}}}}},"404":{"description":"unknown_tool: No public tool with that name exists in the catalog. → Re-read GET /api/public/v1/tools and use an exact name from the catalog.\napproval_intent_not_found: No approval intent with that id exists in this workspace. → Use the intent_id from the 428 approval object; intents expire after 24 hours.\noauth_provider_unknown: No OAuth provider with that slug is enabled. → GET /api/public/v1/oauth/providers for the supported catalog.\nconnection_not_found: No OAuth connection with that id exists in this workspace. → List connections with GET /api/public/v1/oauth/connections and use a current id.","content":{"application/json":{"examples":{"unknown_tool":{"summary":"unknown_tool","value":{"ok":false,"error":{"code":"unknown_tool","message":"No public tool with that name exists in the catalog."}}},"approval_intent_not_found":{"summary":"approval_intent_not_found","value":{"ok":false,"error":{"code":"approval_intent_not_found","message":"No approval intent with that id exists in this workspace."}}},"oauth_provider_unknown":{"summary":"oauth_provider_unknown","value":{"ok":false,"error":{"code":"oauth_provider_unknown","message":"No OAuth provider with that slug is enabled."}}},"connection_not_found":{"summary":"connection_not_found","value":{"ok":false,"error":{"code":"connection_not_found","message":"No OAuth connection with that id exists in this workspace."}}}}}}},"409":{"description":"request_in_progress: Another call with the same idempotency-key is still executing, or an approved confirmation token is already running. → Wait and retry the same idempotency-key to receive the stored response; do not change the body. If the original request is known to have failed, retry with a new idempotency-key. For a confirmation token, call the tool again with no token to get a fresh preview.\nconfirmation_mismatch: The token is bound to a specific tool and argument set; this request differs from what was previewed. → Send the exact body that was previewed, or request a new confirmation for the new body.\nconfirmation_used: That confirmation token was already redeemed. Tokens are single-use. → Request a new confirmation for the next call.\noauth_connection_required: This tool needs a connected third-party account, and none is linked for this workspace. → POST the connect URL from the body with your API key to get an authorization URL, have your operator complete the OAuth flow, then retry the call.","content":{"application/json":{"examples":{"request_in_progress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"Another call with the same idempotency-key is still executing, or an approved confirmation token is already running."}}},"confirmation_mismatch":{"summary":"confirmation_mismatch","value":{"ok":false,"error":{"code":"confirmation_mismatch","message":"The token is bound to a specific tool and argument set; this request differs from what was previewed."}}},"confirmation_used":{"summary":"confirmation_used","value":{"ok":false,"error":{"code":"confirmation_used","message":"That confirmation token was already redeemed. Tokens are single-use."}}},"oauth_connection_required":{"summary":"oauth_connection_required","value":{"ok":false,"error":{"code":"oauth_connection_required","message":"This tool needs a connected third-party account, and none is linked for this workspace."}}}}}}},"410":{"description":"confirmation_expired: The confirmation token passed its 10-minute validity window. → Call again without a token to get a new preview and token.","content":{"application/json":{"examples":{"confirmation_expired":{"summary":"confirmation_expired","value":{"ok":false,"error":{"code":"confirmation_expired","message":"The confirmation token passed its 10-minute validity window."}}}}}}},"422":{"description":"invalid_json: The request body was not valid JSON. → Send a JSON object with content-type: application/json.\ninvalid_input: Arguments failed the tool's JSON Schema. No credits were charged. → Fix the fields listed in error.issues[].path and resend.","content":{"application/json":{"examples":{"invalid_json":{"summary":"invalid_json","value":{"ok":false,"error":{"code":"invalid_json","message":"The request body was not valid JSON."}}},"invalid_input":{"summary":"invalid_input","value":{"ok":false,"error":{"code":"invalid_input","message":"Arguments failed the tool's JSON Schema. No credits were charged."}}}}}}},"428":{"description":"confirmation_required: A side-effecting tool was called without a confirmation token. Nothing was executed or charged. → Show error.preview to your operator. Once they approve, repeat the identical request with header x-confirmation-token: <error.confirmationToken>.","content":{"application/json":{"examples":{"confirmation_required":{"summary":"confirmation_required","value":{"ok":false,"error":{"code":"confirmation_required","message":"A side-effecting tool was called without a confirmation token. Nothing was executed or charged."}}}}}}},"429":{"description":"rate_limited: Over 60 calls per minute for this API key. → Back off ~1 minute, or mint additional keys for parallel workers.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Over 60 calls per minute for this API key."}}}}}}},"500":{"description":"oauth_authorize_failed: The OAuth authorization URL could not be generated. → Retry; if it persists, check that the provider is still enabled.\ncatalog_unavailable: The OAuth provider catalog could not be loaded. → Retry shortly.\nconnections_unavailable: The workspace's OAuth connections could not be listed. → Retry shortly.\nrevoke_failed: The OAuth connection could not be revoked. → Retry; the connection remains active until revocation succeeds.","content":{"application/json":{"examples":{"oauth_authorize_failed":{"summary":"oauth_authorize_failed","value":{"ok":false,"error":{"code":"oauth_authorize_failed","message":"The OAuth authorization URL could not be generated."}}},"catalog_unavailable":{"summary":"catalog_unavailable","value":{"ok":false,"error":{"code":"catalog_unavailable","message":"The OAuth provider catalog could not be loaded."}}},"connections_unavailable":{"summary":"connections_unavailable","value":{"ok":false,"error":{"code":"connections_unavailable","message":"The workspace's OAuth connections could not be listed."}}},"revoke_failed":{"summary":"revoke_failed","value":{"ok":false,"error":{"code":"revoke_failed","message":"The OAuth connection could not be revoked."}}}}}}},"502":{"description":"tool_failed: The upstream tool threw while executing. Reserved credits are refunded automatically. → Retry with backoff; if it persists the integration is down — check status and report.\noauth_callback_failed: The OAuth provider refused the code exchange or the profile lookup. → Restart the connect flow; if it persists the provider app credentials may be misconfigured.\noauth_provider_not_configured: The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY. → The workspace owner should contact support; agents cannot fix this themselves.","content":{"application/json":{"examples":{"tool_failed":{"summary":"tool_failed","value":{"ok":false,"error":{"code":"tool_failed","message":"The upstream tool threw while executing. Reserved credits are refunded automatically."}}},"oauth_callback_failed":{"summary":"oauth_callback_failed","value":{"ok":false,"error":{"code":"oauth_callback_failed","message":"The OAuth provider refused the code exchange or the profile lookup."}}},"oauth_provider_not_configured":{"summary":"oauth_provider_not_configured","value":{"ok":false,"error":{"code":"oauth_provider_not_configured","message":"The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY."}}}}}}},"503":{"description":"metering_unavailable: Credit metering could not be reached, so the call was not authorized or charged. → Retry with backoff; the same idempotency-key is safe to reuse.","content":{"application/json":{"examples":{"metering_unavailable":{"summary":"metering_unavailable","value":{"ok":false,"error":{"code":"metering_unavailable","message":"Credit metering could not be reached, so the call was not authorized or charged."}}}}}}}}}},"/api/public/v1/tools/slack_post_message":{"post":{"operationId":"slack_post_message","summary":"Post Slack message","description":"Post a message to a Slack channel as the workspace's connected Slack identity. Uses the managed OAuth connection — the agent never sees credentials. Requires the workspace to connect Slack first (POST /api/public/v1/oauth/slack/authorize). Side-effecting: requires confirmation. Costs 4 credit(s). Side-effecting: the first call returns 428 confirmation_required with a preview and a single-use confirmationToken; resend the identical body with header x-confirmation-token to execute.","security":[{"agentKey":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Replay-safe key scoped to your API key. A repeated completed call returns the stored response and is not charged again."},{"name":"x-confirmation-token","in":"header","required":false,"schema":{"type":"string"},"description":"Single-use token from a prior 428 confirmation_required response, bound to this exact request body. Omit it on the first call to receive the preview and token."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","description":"Channel name (e.g. #general) or channel ID"},"text":{"type":"string","description":"Message text (Slack mrkdwn supported)"}},"required":["channel","text"],"additionalProperties":false},"examples":{"default":{"summary":"Example call","value":{"channel":"#general","text":"Deploy finished :white_check_mark:"}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"examples":{"default":{"summary":"Success","value":{"ok":true,"requestId":"b0e1c8a2-9f4d-4d0f-9a1e-2c5d7f8e1a30","tool":"slack_post_message","demo":false,"credits":{"charged":4,"balance":496},"result":{"ok":true,"channel":"C0123456789","ts":"1758650400.000100","messageId":"C0123456789:1758650400.000100","postedAt":"2026-09-23T18:00:00.000Z"}}}}}}},"401":{"description":"missing_api_key: No Authorization: Bearer header on the request. → Send Authorization: Bearer sk_agent_… , or POST /api/public/v1/signup to mint a key.\ninvalid_api_key: The key is unknown, revoked, or past its rotation grace window. → Rotate with POST /api/public/v1/keys/rotate, or create a new key in the console.\nkey_expired: The key passed the expiry date set by its owner. → Rotate the key or issue a new one in the console.","content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"ok":false,"error":{"code":"missing_api_key","message":"No Authorization: Bearer header on the request."}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"ok":false,"error":{"code":"invalid_api_key","message":"The key is unknown, revoked, or past its rotation grace window."}}},"key_expired":{"summary":"key_expired","value":{"ok":false,"error":{"code":"key_expired","message":"The key passed the expiry date set by its owner."}}}}}}},"402":{"description":"insufficient_credits: The workspace balance is below this tool's price. Nothing was executed or charged. → Pay machine-to-machine: the body carries an x402 accepts[] offer — settle it and retry the same request with an X-PAYMENT header. Humans can instead buy credits via POST /api/public/v1/claim.\npayment_failed: An X-PAYMENT header was supplied but the facilitator could not verify or settle it. → Re-read accepts[0] from a fresh 402, rebuild the payment payload for the exact amount, asset and network, and retry.","content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"ok":false,"error":{"code":"insufficient_credits","message":"The workspace balance is below this tool's price. Nothing was executed or charged.","required":5,"balance":2}}},"payment_failed":{"summary":"payment_failed","value":{"ok":false,"error":{"code":"payment_failed","message":"An X-PAYMENT header was supplied but the facilitator could not verify or settle it."}}}}}}},"403":{"description":"budget_exceeded: The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key. → Wait for the window to roll over, or ask the key owner to raise the cap in the console.\ntool_not_allowed: This key has a tool allowlist that does not include the requested tool. → Call an allowed tool, or ask the key owner to widen the allowlist.\ntool_disabled: The workspace owner has disabled this tool for the org. → Enable the tool in the console, or call a different tool.\ninsufficient_scope: The key is valid but does not carry the tools:invoke scope. → Issue a key with tools:invoke from the console and retry with it.\nconfirmation_invalid: The x-confirmation-token header is unknown or belongs to another workspace. → Call the tool without a token to receive a fresh preview and token, then retry.","content":{"application/json":{"examples":{"budget_exceeded":{"summary":"budget_exceeded","value":{"ok":false,"error":{"code":"budget_exceeded","message":"The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key."}}},"tool_not_allowed":{"summary":"tool_not_allowed","value":{"ok":false,"error":{"code":"tool_not_allowed","message":"This key has a tool allowlist that does not include the requested tool."}}},"tool_disabled":{"summary":"tool_disabled","value":{"ok":false,"error":{"code":"tool_disabled","message":"The workspace owner has disabled this tool for the org."}}},"insufficient_scope":{"summary":"insufficient_scope","value":{"ok":false,"error":{"code":"insufficient_scope","message":"The key is valid but does not carry the tools:invoke scope."}}},"confirmation_invalid":{"summary":"confirmation_invalid","value":{"ok":false,"error":{"code":"confirmation_invalid","message":"The x-confirmation-token header is unknown or belongs to another workspace."}}}}}}},"404":{"description":"unknown_tool: No public tool with that name exists in the catalog. → Re-read GET /api/public/v1/tools and use an exact name from the catalog.\napproval_intent_not_found: No approval intent with that id exists in this workspace. → Use the intent_id from the 428 approval object; intents expire after 24 hours.\noauth_provider_unknown: No OAuth provider with that slug is enabled. → GET /api/public/v1/oauth/providers for the supported catalog.\nconnection_not_found: No OAuth connection with that id exists in this workspace. → List connections with GET /api/public/v1/oauth/connections and use a current id.","content":{"application/json":{"examples":{"unknown_tool":{"summary":"unknown_tool","value":{"ok":false,"error":{"code":"unknown_tool","message":"No public tool with that name exists in the catalog."}}},"approval_intent_not_found":{"summary":"approval_intent_not_found","value":{"ok":false,"error":{"code":"approval_intent_not_found","message":"No approval intent with that id exists in this workspace."}}},"oauth_provider_unknown":{"summary":"oauth_provider_unknown","value":{"ok":false,"error":{"code":"oauth_provider_unknown","message":"No OAuth provider with that slug is enabled."}}},"connection_not_found":{"summary":"connection_not_found","value":{"ok":false,"error":{"code":"connection_not_found","message":"No OAuth connection with that id exists in this workspace."}}}}}}},"409":{"description":"request_in_progress: Another call with the same idempotency-key is still executing, or an approved confirmation token is already running. → Wait and retry the same idempotency-key to receive the stored response; do not change the body. If the original request is known to have failed, retry with a new idempotency-key. For a confirmation token, call the tool again with no token to get a fresh preview.\nconfirmation_mismatch: The token is bound to a specific tool and argument set; this request differs from what was previewed. → Send the exact body that was previewed, or request a new confirmation for the new body.\nconfirmation_used: That confirmation token was already redeemed. Tokens are single-use. → Request a new confirmation for the next call.\noauth_connection_required: This tool needs a connected third-party account, and none is linked for this workspace. → POST the connect URL from the body with your API key to get an authorization URL, have your operator complete the OAuth flow, then retry the call.","content":{"application/json":{"examples":{"request_in_progress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"Another call with the same idempotency-key is still executing, or an approved confirmation token is already running."}}},"confirmation_mismatch":{"summary":"confirmation_mismatch","value":{"ok":false,"error":{"code":"confirmation_mismatch","message":"The token is bound to a specific tool and argument set; this request differs from what was previewed."}}},"confirmation_used":{"summary":"confirmation_used","value":{"ok":false,"error":{"code":"confirmation_used","message":"That confirmation token was already redeemed. Tokens are single-use."}}},"oauth_connection_required":{"summary":"oauth_connection_required","value":{"ok":false,"error":{"code":"oauth_connection_required","message":"This tool needs a connected third-party account, and none is linked for this workspace."}}}}}}},"410":{"description":"confirmation_expired: The confirmation token passed its 10-minute validity window. → Call again without a token to get a new preview and token.","content":{"application/json":{"examples":{"confirmation_expired":{"summary":"confirmation_expired","value":{"ok":false,"error":{"code":"confirmation_expired","message":"The confirmation token passed its 10-minute validity window."}}}}}}},"422":{"description":"invalid_json: The request body was not valid JSON. → Send a JSON object with content-type: application/json.\ninvalid_input: Arguments failed the tool's JSON Schema. No credits were charged. → Fix the fields listed in error.issues[].path and resend.","content":{"application/json":{"examples":{"invalid_json":{"summary":"invalid_json","value":{"ok":false,"error":{"code":"invalid_json","message":"The request body was not valid JSON."}}},"invalid_input":{"summary":"invalid_input","value":{"ok":false,"error":{"code":"invalid_input","message":"Arguments failed the tool's JSON Schema. No credits were charged."}}}}}}},"428":{"description":"confirmation_required: A side-effecting tool was called without a confirmation token. Nothing was executed or charged. → Show error.preview to your operator. Once they approve, repeat the identical request with header x-confirmation-token: <error.confirmationToken>.","content":{"application/json":{"examples":{"confirmation_required":{"summary":"confirmation_required","value":{"ok":false,"error":{"code":"confirmation_required","message":"A side-effecting tool was called without a confirmation token. Nothing was executed or charged."}}}}}}},"429":{"description":"rate_limited: Over 60 calls per minute for this API key. → Back off ~1 minute, or mint additional keys for parallel workers.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Over 60 calls per minute for this API key."}}}}}}},"500":{"description":"oauth_authorize_failed: The OAuth authorization URL could not be generated. → Retry; if it persists, check that the provider is still enabled.\ncatalog_unavailable: The OAuth provider catalog could not be loaded. → Retry shortly.\nconnections_unavailable: The workspace's OAuth connections could not be listed. → Retry shortly.\nrevoke_failed: The OAuth connection could not be revoked. → Retry; the connection remains active until revocation succeeds.","content":{"application/json":{"examples":{"oauth_authorize_failed":{"summary":"oauth_authorize_failed","value":{"ok":false,"error":{"code":"oauth_authorize_failed","message":"The OAuth authorization URL could not be generated."}}},"catalog_unavailable":{"summary":"catalog_unavailable","value":{"ok":false,"error":{"code":"catalog_unavailable","message":"The OAuth provider catalog could not be loaded."}}},"connections_unavailable":{"summary":"connections_unavailable","value":{"ok":false,"error":{"code":"connections_unavailable","message":"The workspace's OAuth connections could not be listed."}}},"revoke_failed":{"summary":"revoke_failed","value":{"ok":false,"error":{"code":"revoke_failed","message":"The OAuth connection could not be revoked."}}}}}}},"502":{"description":"tool_failed: The upstream tool threw while executing. Reserved credits are refunded automatically. → Retry with backoff; if it persists the integration is down — check status and report.\noauth_callback_failed: The OAuth provider refused the code exchange or the profile lookup. → Restart the connect flow; if it persists the provider app credentials may be misconfigured.\noauth_provider_not_configured: The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY. → The workspace owner should contact support; agents cannot fix this themselves.","content":{"application/json":{"examples":{"tool_failed":{"summary":"tool_failed","value":{"ok":false,"error":{"code":"tool_failed","message":"The upstream tool threw while executing. Reserved credits are refunded automatically."}}},"oauth_callback_failed":{"summary":"oauth_callback_failed","value":{"ok":false,"error":{"code":"oauth_callback_failed","message":"The OAuth provider refused the code exchange or the profile lookup."}}},"oauth_provider_not_configured":{"summary":"oauth_provider_not_configured","value":{"ok":false,"error":{"code":"oauth_provider_not_configured","message":"The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY."}}}}}}},"503":{"description":"metering_unavailable: Credit metering could not be reached, so the call was not authorized or charged. → Retry with backoff; the same idempotency-key is safe to reuse.","content":{"application/json":{"examples":{"metering_unavailable":{"summary":"metering_unavailable","value":{"ok":false,"error":{"code":"metering_unavailable","message":"Credit metering could not be reached, so the call was not authorized or charged."}}}}}}}}}},"/api/public/v1/tools/github_create_issue":{"post":{"operationId":"github_create_issue","summary":"Create GitHub issue","description":"Create an issue in a GitHub repository as the workspace's connected GitHub identity. Uses the managed OAuth connection — the agent never sees credentials. Requires the workspace to connect GitHub first (POST /api/public/v1/oauth/github/authorize). Side-effecting: requires confirmation. Costs 4 credit(s). Side-effecting: the first call returns 428 confirmation_required with a preview and a single-use confirmationToken; resend the identical body with header x-confirmation-token to execute.","security":[{"agentKey":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Replay-safe key scoped to your API key. A repeated completed call returns the stored response and is not charged again."},{"name":"x-confirmation-token","in":"header","required":false,"schema":{"type":"string"},"description":"Single-use token from a prior 428 confirmation_required response, bound to this exact request body. Omit it on the first call to receive the preview and token."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"owner":{"type":"string","description":"Repository owner (user or organization)"},"repo":{"type":"string","description":"Repository name"},"title":{"type":"string","description":"Issue title"},"body":{"type":"string","description":"Issue body in markdown"}},"required":["owner","repo","title"],"additionalProperties":false},"examples":{"default":{"summary":"Example call","value":{"owner":"octocat","repo":"hello-world","title":"Found a bug","body":"Steps to reproduce..."}}}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"examples":{"default":{"summary":"Success","value":{"ok":true,"requestId":"b0e1c8a2-9f4d-4d0f-9a1e-2c5d7f8e1a30","tool":"github_create_issue","demo":false,"credits":{"charged":4,"balance":496},"result":{"ok":true,"issueNumber":1347,"url":"https://github.com/octocat/hello-world/issues/1347","state":"open","createdAt":"2026-09-23T18:00:00.000Z"}}}}}}},"401":{"description":"missing_api_key: No Authorization: Bearer header on the request. → Send Authorization: Bearer sk_agent_… , or POST /api/public/v1/signup to mint a key.\ninvalid_api_key: The key is unknown, revoked, or past its rotation grace window. → Rotate with POST /api/public/v1/keys/rotate, or create a new key in the console.\nkey_expired: The key passed the expiry date set by its owner. → Rotate the key or issue a new one in the console.","content":{"application/json":{"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"ok":false,"error":{"code":"missing_api_key","message":"No Authorization: Bearer header on the request."}}},"invalid_api_key":{"summary":"invalid_api_key","value":{"ok":false,"error":{"code":"invalid_api_key","message":"The key is unknown, revoked, or past its rotation grace window."}}},"key_expired":{"summary":"key_expired","value":{"ok":false,"error":{"code":"key_expired","message":"The key passed the expiry date set by its owner."}}}}}}},"402":{"description":"insufficient_credits: The workspace balance is below this tool's price. Nothing was executed or charged. → Pay machine-to-machine: the body carries an x402 accepts[] offer — settle it and retry the same request with an X-PAYMENT header. Humans can instead buy credits via POST /api/public/v1/claim.\npayment_failed: An X-PAYMENT header was supplied but the facilitator could not verify or settle it. → Re-read accepts[0] from a fresh 402, rebuild the payment payload for the exact amount, asset and network, and retry.","content":{"application/json":{"examples":{"insufficient_credits":{"summary":"insufficient_credits","value":{"ok":false,"error":{"code":"insufficient_credits","message":"The workspace balance is below this tool's price. Nothing was executed or charged.","required":5,"balance":2}}},"payment_failed":{"summary":"payment_failed","value":{"ok":false,"error":{"code":"payment_failed","message":"An X-PAYMENT header was supplied but the facilitator could not verify or settle it."}}}}}}},"403":{"description":"budget_exceeded: The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key. → Wait for the window to roll over, or ask the key owner to raise the cap in the console.\ntool_not_allowed: This key has a tool allowlist that does not include the requested tool. → Call an allowed tool, or ask the key owner to widen the allowlist.\ntool_disabled: The workspace owner has disabled this tool for the org. → Enable the tool in the console, or call a different tool.\ninsufficient_scope: The key is valid but does not carry the tools:invoke scope. → Issue a key with tools:invoke from the console and retry with it.\nconfirmation_invalid: The x-confirmation-token header is unknown or belongs to another workspace. → Call the tool without a token to receive a fresh preview and token, then retry.","content":{"application/json":{"examples":{"budget_exceeded":{"summary":"budget_exceeded","value":{"ok":false,"error":{"code":"budget_exceeded","message":"The call would exceed a per-call, 24-hour, or lifetime credit cap set on this key."}}},"tool_not_allowed":{"summary":"tool_not_allowed","value":{"ok":false,"error":{"code":"tool_not_allowed","message":"This key has a tool allowlist that does not include the requested tool."}}},"tool_disabled":{"summary":"tool_disabled","value":{"ok":false,"error":{"code":"tool_disabled","message":"The workspace owner has disabled this tool for the org."}}},"insufficient_scope":{"summary":"insufficient_scope","value":{"ok":false,"error":{"code":"insufficient_scope","message":"The key is valid but does not carry the tools:invoke scope."}}},"confirmation_invalid":{"summary":"confirmation_invalid","value":{"ok":false,"error":{"code":"confirmation_invalid","message":"The x-confirmation-token header is unknown or belongs to another workspace."}}}}}}},"404":{"description":"unknown_tool: No public tool with that name exists in the catalog. → Re-read GET /api/public/v1/tools and use an exact name from the catalog.\napproval_intent_not_found: No approval intent with that id exists in this workspace. → Use the intent_id from the 428 approval object; intents expire after 24 hours.\noauth_provider_unknown: No OAuth provider with that slug is enabled. → GET /api/public/v1/oauth/providers for the supported catalog.\nconnection_not_found: No OAuth connection with that id exists in this workspace. → List connections with GET /api/public/v1/oauth/connections and use a current id.","content":{"application/json":{"examples":{"unknown_tool":{"summary":"unknown_tool","value":{"ok":false,"error":{"code":"unknown_tool","message":"No public tool with that name exists in the catalog."}}},"approval_intent_not_found":{"summary":"approval_intent_not_found","value":{"ok":false,"error":{"code":"approval_intent_not_found","message":"No approval intent with that id exists in this workspace."}}},"oauth_provider_unknown":{"summary":"oauth_provider_unknown","value":{"ok":false,"error":{"code":"oauth_provider_unknown","message":"No OAuth provider with that slug is enabled."}}},"connection_not_found":{"summary":"connection_not_found","value":{"ok":false,"error":{"code":"connection_not_found","message":"No OAuth connection with that id exists in this workspace."}}}}}}},"409":{"description":"request_in_progress: Another call with the same idempotency-key is still executing, or an approved confirmation token is already running. → Wait and retry the same idempotency-key to receive the stored response; do not change the body. If the original request is known to have failed, retry with a new idempotency-key. For a confirmation token, call the tool again with no token to get a fresh preview.\nconfirmation_mismatch: The token is bound to a specific tool and argument set; this request differs from what was previewed. → Send the exact body that was previewed, or request a new confirmation for the new body.\nconfirmation_used: That confirmation token was already redeemed. Tokens are single-use. → Request a new confirmation for the next call.\noauth_connection_required: This tool needs a connected third-party account, and none is linked for this workspace. → POST the connect URL from the body with your API key to get an authorization URL, have your operator complete the OAuth flow, then retry the call.","content":{"application/json":{"examples":{"request_in_progress":{"summary":"request_in_progress","value":{"ok":false,"error":{"code":"request_in_progress","message":"Another call with the same idempotency-key is still executing, or an approved confirmation token is already running."}}},"confirmation_mismatch":{"summary":"confirmation_mismatch","value":{"ok":false,"error":{"code":"confirmation_mismatch","message":"The token is bound to a specific tool and argument set; this request differs from what was previewed."}}},"confirmation_used":{"summary":"confirmation_used","value":{"ok":false,"error":{"code":"confirmation_used","message":"That confirmation token was already redeemed. Tokens are single-use."}}},"oauth_connection_required":{"summary":"oauth_connection_required","value":{"ok":false,"error":{"code":"oauth_connection_required","message":"This tool needs a connected third-party account, and none is linked for this workspace."}}}}}}},"410":{"description":"confirmation_expired: The confirmation token passed its 10-minute validity window. → Call again without a token to get a new preview and token.","content":{"application/json":{"examples":{"confirmation_expired":{"summary":"confirmation_expired","value":{"ok":false,"error":{"code":"confirmation_expired","message":"The confirmation token passed its 10-minute validity window."}}}}}}},"422":{"description":"invalid_json: The request body was not valid JSON. → Send a JSON object with content-type: application/json.\ninvalid_input: Arguments failed the tool's JSON Schema. No credits were charged. → Fix the fields listed in error.issues[].path and resend.","content":{"application/json":{"examples":{"invalid_json":{"summary":"invalid_json","value":{"ok":false,"error":{"code":"invalid_json","message":"The request body was not valid JSON."}}},"invalid_input":{"summary":"invalid_input","value":{"ok":false,"error":{"code":"invalid_input","message":"Arguments failed the tool's JSON Schema. No credits were charged."}}}}}}},"428":{"description":"confirmation_required: A side-effecting tool was called without a confirmation token. Nothing was executed or charged. → Show error.preview to your operator. Once they approve, repeat the identical request with header x-confirmation-token: <error.confirmationToken>.","content":{"application/json":{"examples":{"confirmation_required":{"summary":"confirmation_required","value":{"ok":false,"error":{"code":"confirmation_required","message":"A side-effecting tool was called without a confirmation token. Nothing was executed or charged."}}}}}}},"429":{"description":"rate_limited: Over 60 calls per minute for this API key. → Back off ~1 minute, or mint additional keys for parallel workers.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"ok":false,"error":{"code":"rate_limited","message":"Over 60 calls per minute for this API key."}}}}}}},"500":{"description":"oauth_authorize_failed: The OAuth authorization URL could not be generated. → Retry; if it persists, check that the provider is still enabled.\ncatalog_unavailable: The OAuth provider catalog could not be loaded. → Retry shortly.\nconnections_unavailable: The workspace's OAuth connections could not be listed. → Retry shortly.\nrevoke_failed: The OAuth connection could not be revoked. → Retry; the connection remains active until revocation succeeds.","content":{"application/json":{"examples":{"oauth_authorize_failed":{"summary":"oauth_authorize_failed","value":{"ok":false,"error":{"code":"oauth_authorize_failed","message":"The OAuth authorization URL could not be generated."}}},"catalog_unavailable":{"summary":"catalog_unavailable","value":{"ok":false,"error":{"code":"catalog_unavailable","message":"The OAuth provider catalog could not be loaded."}}},"connections_unavailable":{"summary":"connections_unavailable","value":{"ok":false,"error":{"code":"connections_unavailable","message":"The workspace's OAuth connections could not be listed."}}},"revoke_failed":{"summary":"revoke_failed","value":{"ok":false,"error":{"code":"revoke_failed","message":"The OAuth connection could not be revoked."}}}}}}},"502":{"description":"tool_failed: The upstream tool threw while executing. Reserved credits are refunded automatically. → Retry with backoff; if it persists the integration is down — check status and report.\noauth_callback_failed: The OAuth provider refused the code exchange or the profile lookup. → Restart the connect flow; if it persists the provider app credentials may be misconfigured.\noauth_provider_not_configured: The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY. → The workspace owner should contact support; agents cannot fix this themselves.","content":{"application/json":{"examples":{"tool_failed":{"summary":"tool_failed","value":{"ok":false,"error":{"code":"tool_failed","message":"The upstream tool threw while executing. Reserved credits are refunded automatically."}}},"oauth_callback_failed":{"summary":"oauth_callback_failed","value":{"ok":false,"error":{"code":"oauth_callback_failed","message":"The OAuth provider refused the code exchange or the profile lookup."}}},"oauth_provider_not_configured":{"summary":"oauth_provider_not_configured","value":{"ok":false,"error":{"code":"oauth_provider_not_configured","message":"The OAuth provider is enabled in the catalog but its app credentials are missing on RELAY."}}}}}}},"503":{"description":"metering_unavailable: Credit metering could not be reached, so the call was not authorized or charged. → Retry with backoff; the same idempotency-key is safe to reuse.","content":{"application/json":{"examples":{"metering_unavailable":{"summary":"metering_unavailable","value":{"ok":false,"error":{"code":"metering_unavailable","message":"Credit metering could not be reached, so the call was not authorized or charged."}}}}}}}}}},"/api/public/v1/signup":{"post":{"operationId":"signup","summary":"Create a workspace and API key (no auth required)","description":"Agent self-serve onboarding. Returns a one-time API key, a free starter credit grant and a claim URL for a human operator.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","maxLength":80},"email":{"type":"string","format":"email"}}}}}},"responses":{"201":{"description":"Workspace created; apiKey is shown once"},"422":{"description":"Invalid signup payload"},"429":{"description":"Too many workspaces created from this address"}}}},"/api/public/v1/claim":{"post":{"operationId":"createClaimLink","summary":"Mint a claim URL so a human can take ownership and buy credits","security":[{"agentKey":[]}],"responses":{"200":{"description":"Claim URL and expiry"},"401":{"description":"Missing or invalid API key"},"409":{"description":"Workspace already claimed"}}}},"/api/public/v1/keys/rotate":{"post":{"operationId":"rotateKey","summary":"Rotate the calling key (old key keeps working briefly)","security":[{"agentKey":[]}],"responses":{"200":{"description":"New apiKey, shown once"},"401":{"description":"Missing or invalid API key"}}}},"/api/public/v1/credits/purchase":{"post":{"operationId":"purchaseCredits","summary":"Buy credits machine-to-machine over x402 (USDC on Base)","description":"POST {credits} to receive a 402 with an x402 accepts[] offer. Settle it, then retry the same request with an X-PAYMENT header to have the credits added.","security":[{"agentKey":[]}],"responses":{"200":{"description":"Credits added, with settlement receipt"},"402":{"description":"Payment required — body carries the x402 offer"},"422":{"description":"credits out of range"}}}},"/api/public/v1/me":{"get":{"operationId":"getAccount","summary":"Account, credit balance and rate limit","security":[{"agentKey":[]}],"responses":{"200":{"description":"Account status"}}}},"/api/public/v1/tools":{"get":{"operationId":"listTools","summary":"Machine-readable tool catalog (no auth required)","responses":{"200":{"description":"Tool catalog"}}}}}}