{ "openapi": "3.1.0", "info": { "title": "Attestify OS API", "version": "1.7.0", "description": "Attestify OS is an agent execution, routing, payment, memory, receipt, and verification layer for autonomous agents. Discover capabilities and pricing for free, then use the router-first paid /api/run flow to select a lane, execute work, settle x402 payment, and inspect public proof.\n\nThe governance layer (POST /api/pre-auth → execute payment → POST /api/pre-auth/close) provides a cryptographically auditable 3-leg compliance loop: every agent payment is checked against mandate policies before execution and reported back after, with an orphan detector escalating any unclosed transaction.\n\nThe observability layer (/api/audit, /api/analytics, /api/benchmark, /api/ledger) provides tenant-scoped insight into spend, performance, and verification outcomes. The control layer (/api/authorize, /api/approvals, /api/budgets, /api/policies, /api/control-tower) provides programmatic governance management for multi-agent deployments.\n\nNamespace note: /api/loop is the canonical execution primitive; /api/loops is the read-only proof surface. /api/settle is canonical; /api/settlement is a deprecated alias (will redirect); /api/settlements lists records. /api/lane is canonical lane management; /api/lanes is the read-only catalogue. /api/onboard is canonical; /api/onboarding is a deprecated alias.", "x-summary": "Router-first paid agent execution with x402/USDC micropayments, persistent memory, receipts, and verification. Free to discover — pay per run on Base. Governance layer provides pre-authorisation and close-out audit trail for autonomous payments. Observability and control layers surface spend analytics, policy management, and approval workflows.", "x-logo": { "url": "https://attestifyos.com/logo.svg", "altText": "Attestify OS" }, "x-agent-optimised": true, "x-free-discovery": [ "/api/capabilities", "/api/pricing", "/api/providers", "/api/route", "/api/health", "/api/env-check" ], "x-governance-endpoints": [ "/api/pre-auth", "/api/pre-auth/close" ], "x-paid-entry-point": "/api/run", "x-auth-endpoints": { "robinhood": { "connect": "GET /api/rh/auth (scaffold — see endpoint description; not yet wired to real session/tenant data)", "callback": "GET /api/rh/auth/callback (handled automatically by OAuth redirect; scaffold, returns JSON not a redirect)", "revoke": "POST /api/rh/auth/revoke (scaffold, takes rh_account_id)" } }, "x-payment-protocol": "x402", "x-payment-currency": "USDC", "x-payment-network": "eip155:8453", "x-cheapest-test-lane": "comedian-v1", "x-cheapest-test-price-usdc": 0.01, "x-llms-txt": "https://attestifyos.com/llms.txt", "x-llms-full-txt": "https://attestifyos.com/llms-full.txt", "x-mcp-manifest": "https://attestifyos.com/.well-known/mcp.json", "x-payment-methods": "https://attestifyos.com/.well-known/payment-methods.json", "x-agent-manifest": "https://attestifyos.com/.well-known/agent.json", "x-agents-directory": "https://attestifyos.com/.well-known/agents.json", "x-x402-manifest": "https://attestifyos.com/.well-known/x402.json", "x-namespace-canonical": { "/api/loop": "execution primitive — POST to run a loop", "/api/loops": "read-only proof surface — GET recent loop history", "/api/settle": "canonical settlement — use this", "/api/settlement": "deprecated alias for /api/settle — will 308 redirect", "/api/settlements": "read-only settlement records list", "/api/lane": "canonical lane management — use this", "/api/lanes": "read-only lane catalogue", "/api/onboard": "canonical onboarding — use this", "/api/onboarding": "deprecated alias for /api/onboard — will 308 redirect" }, "contact": { "name": "Attestify OS", "url": "https://attestifyos.com", "email": "hello@attestifyos.com" } }, "servers": [ { "url": "https://attestifyos.com", "description": "Production" } ], "tags": [ { "name": "Discovery", "description": "Machine-readable discovery and preflight inspection surfaces." }, { "name": "Routing", "description": "Task-to-lane routing and route recommendation surfaces." }, { "name": "Execution", "description": "Paid execution endpoints for orchestrated and lower-level loop runs." }, { "name": "Governance", "description": "Pre-authorisation and close-out compliance loop. Every autonomous payment must pass through POST /api/pre-auth to receive a signed auth token before execution, then POST /api/pre-auth/close to record the outcome. An orphan detector escalates any unclosed transaction after 10 minutes." }, { "name": "Proof", "description": "Receipts, loop history, agent reputation, and verification evidence." }, { "name": "Memory", "description": "Persistent session memory surfaces." }, { "name": "Admin", "description": "Administrative endpoints for tenant key management. Requires the X-Admin-Key header." }, { "name": "Observability", "description": "Tenant-scoped insight surfaces — audit logs, analytics, benchmark data, and the payments ledger. All endpoints require X-API-Key." }, { "name": "Control", "description": "Programmatic governance management — authorisation overrides, approval workflows, budget configuration, policy management, and the unified control-tower status surface. All write endpoints require X-API-Key." }, { "name": "Wallets", "description": "Agent wallet management — balances, top-up, and escrow surfaces for USDC on Base." }, { "name": "rh", "description": "Robinhood brokerage integration — OAuth account linking, governed trading execution, instrument-aware run approval, and enriched attestation receipts. Supports equity, perp, crypto, RWA, Earn, and credit-card spend intents." } ], "security": [], "paths": { "/api/health": { "get": { "tags": [ "Discovery" ], "summary": "Health check", "description": "Returns the live health status of the Attestify OS platform, including Redis and Supabase connectivity. Free endpoint — no authentication required.", "operationId": "getHealth", "responses": { "200": { "description": "Platform is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "503": { "description": "One or more dependencies are degraded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/api/env-check": { "get": { "tags": [ "Discovery" ], "summary": "Environment variable presence check", "description": "Surfaces presence/absence of required and optional environment variables grouped by service. Secrets shown as [set, N chars], plain vars as [set], missing as [missing]. Never exposes actual values. Returns status: ok | incomplete with missing_required[] list. Safe for CI pre-flight.", "operationId": "getEnvCheck", "responses": { "200": { "description": "Environment report" } } } }, "/api/capabilities": { "get": { "tags": [ "Discovery" ], "summary": "Get capabilities", "description": "Returns a machine-readable overview of Attestify product layers, free endpoints, paid endpoints, and high-level platform features.", "operationId": "getCapabilities", "responses": { "200": { "description": "Capabilities surface", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilitiesResponse" } } } } } } }, "/api/pricing": { "get": { "tags": [ "Discovery" ], "summary": "Get pricing", "description": "Returns machine-readable pricing hints so builders and agents can reason about cost before spending.", "operationId": "getPricing", "responses": { "200": { "description": "Pricing surface", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingSurfaceResponse" } } } } } } }, "/api/providers": { "get": { "tags": [ "Discovery" ], "summary": "List providers", "description": "Returns routeable providers and trust or pricing hints before execution.", "operationId": "getProviders", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "network", "in": "query", "schema": { "type": "string" } }, { "name": "trusted_only", "in": "query", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Provider list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvidersResponse" } } } } } } }, "/api/route": { "post": { "tags": [ "Routing" ], "summary": "Recommend a route", "description": "Returns a routing recommendation before paid execution when the caller wants help choosing a lane.", "operationId": "routeTask", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteRequest" } } } }, "responses": { "200": { "description": "Routing recommendation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteRecommendationResponse" } } } }, "400": { "description": "Invalid routing request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/routing-intel": { "post": { "tags": [ "Routing" ], "summary": "Get pre-flight routing intelligence", "description": "Returns recommended lane, estimated USDC cost, and routing posture before committing spend. Free — no x402 payment required.", "operationId": "getRoutingIntel", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "string" } }, "required": [ "task" ] } } } }, "responses": { "200": { "description": "Routing recommendation" } } } }, "/api/authorize": { "post": { "tags": [ "Control" ], "summary": "Issue an authorisation override", "description": "Allows a mandate holder or admin to issue a one-time authorisation override for an agent payment that was denied by policy. The override is time-limited and scoped to a specific agent, amount, and merchant. Requires X-API-Key.", "operationId": "issueAuthorization", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeRequest" } } } }, "responses": { "200": { "description": "Authorisation override issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/approvals": { "get": { "tags": [ "Control" ], "summary": "List pending approvals", "description": "Returns a list of agent payment requests that are pending human approval. Requires X-API-Key.", "operationId": "listApprovals", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "all" ], "default": "pending" } }, { "name": "agent_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "domain", "in": "query", "schema": { "type": "string", "enum": [ "core", "rh", "cb" ], "default": "core" }, "description": "core-platform (Redis-backed) approvals only. rh/cb return an empty list with a pointer to /api/rh/receipts or /api/cb/receipts, since those integrations store approvals in separate tables entirely." } ], "responses": { "200": { "description": "Approval list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalsListResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Control" ], "summary": "Approve or reject a pending payment", "description": "Approves or rejects a pending agent payment request. Requires X-API-Key.", "operationId": "resolveApproval", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalResolutionRequest" } } } }, "responses": { "200": { "description": "Approval decision recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalResolutionResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Approval record not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/budgets": { "get": { "tags": [ "Control" ], "summary": "Get budget configuration", "description": "Returns the current budget configuration for the authenticated tenant. Requires X-API-Key.", "operationId": "getBudgets", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Budget configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetConfigResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Control" ], "summary": "Update budget configuration", "description": "Updates the budget limits for the authenticated tenant. Requires X-API-Key.", "operationId": "updateBudgets", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetUpdateRequest" } } } }, "responses": { "200": { "description": "Budget updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetConfigResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/rh/auth": { "get": { "tags": [ "rh" ], "summary": "Initiate Robinhood OAuth account linking (scaffold)", "description": "Scaffold implementation (see app/api/rh/auth/route.js) — not yet wired to real session/tenant data. Takes no query parameters; the OAuth `state` is a plain `crypto.randomUUID()` with no session or user information encoded into it. Redirects to `RH_OAUTH_AUTHORIZE_URL` (defaults to a placeholder `https://robinhood.example.com/oauth/authorize` if unset) with `client_id`, `redirect_uri`, `scope`, and `state` appended. Returns 503 if `RH_OAUTH_CLIENT_ID` is not configured.", "operationId": "rhAuthInitiate", "parameters": [ ], "responses": { "302": { "description": "Redirect to Robinhood OAuth authorisation URL" }, "503": { "description": "OAuth not configured — RH_OAUTH_CLIENT_ID or RH_OAUTH_REDIRECT_URI env vars missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/rh/auth/callback": { "get": { "tags": [ "rh" ], "summary": "Robinhood OAuth callback (internal, scaffold)", "description": "Scaffold implementation (see app/api/rh/auth/callback/route.js) — not yet wired to real session/tenant data. Exchanges `code` for a token via `RH_OAUTH_TOKEN_URL` (a placeholder if unset); if that exchange fails or is unreachable, silently falls back to stub `stub_access_*`/`stub_refresh_*` token values rather than erroring. AES-256-GCM encrypts the token payload and upserts into `robinhood.rh_accounts` keyed by a synthetic `rh_account_id` derived from `code`, with `tenant_id` hardcoded to the literal string `'oauth-scaffold'` for every caller — not yet tied to the real tenant. Returns a 200 JSON status object; it does not redirect anywhere. Returns 503 if `RH_OAUTH_CLIENT_ID`, `RH_OAUTH_CLIENT_SECRET`, or `AES_ENCRYPTION_KEY` is not configured.", "operationId": "rhAuthCallback", "parameters": [ { "name": "code", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Authorisation code from Robinhood" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque value echoed back from the /api/rh/auth redirect. Not currently validated or decoded — carries no session/user information." } ], "responses": { "200": { "description": "JSON status object: { domain, oauth_ready, token_stored, account_stub_created, encrypted }" }, "400": { "description": "Missing code query parameter" }, "503": { "description": "OAuth not configured — RH_OAUTH_CLIENT_ID, RH_OAUTH_CLIENT_SECRET, or AES_ENCRYPTION_KEY env vars missing" } } } }, "/api/rh/auth/revoke": { "post": { "tags": [ "rh" ], "summary": "Revoke Robinhood account link (scaffold)", "description": "Scaffold implementation (see app/api/rh/auth/revoke/route.js). Takes `rh_account_id` (not `session_id`) and sets `metadata.revoked_at` on the matching `robinhood.rh_accounts` row via PATCH — it does not delete the row, and does not call any Robinhood revocation endpoint. Always returns 200, including when `rh_account_id` is omitted or matches no row.", "operationId": "rhAuthRevoke", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "rh_account_id": { "type": "string", "description": "rh_account_id whose rh_accounts row's metadata.revoked_at should be set. If omitted, the endpoint still returns 200 and is a no-op." } } } } } }, "responses": { "200": { "description": "{ domain: 'robinhood', revoked: true, rh_account_id }, whether or not a matching row existed" } } } }, "/api/rh/run": { "post": { "tags": [ "rh" ], "summary": "Execute a governed Robinhood trade run", "description": "Executes a governed trading run via the Robinhood brokerage integration. Requires X-API-Key. The run is evaluated against the tenant spend policy before execution. Supply `instrument_type` to route through asset-class-specific policy sets (equity, perp, crypto, rwa, earn, spend).", "operationId": "rhRun", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tenant_id", "symbol", "side", "quantity" ], "properties": { "tenant_id": { "type": "string" }, "symbol": { "type": "string", "description": "Ticker symbol, e.g. AAPL" }, "side": { "type": "string", "enum": [ "buy", "sell", "long", "short" ] }, "quantity": { "type": "number", "description": "Number of shares, contracts, or fractional units" }, "price_limit": { "type": "number", "description": "Optional limit price in USD" }, "instrument_type": { "type": "string", "enum": [ "equity", "perp", "crypto", "rwa", "earn", "spend" ], "description": "Asset class — determines which policy set and receipt schema to apply. Defaults to equity." }, "leverage": { "type": "number", "description": "Leverage multiplier (perp only)" }, "notional_usdc": { "type": "number", "description": "Notional position value in USDC (perp/rwa)" }, "policy_id": { "type": "string", "description": "Override spend policy ID; defaults to tenant default for the instrument_type" } } } } } }, "responses": { "200": { "description": "Trade run executed and settled" }, "202": { "description": "Trade run queued pending approval (instrument-aware approval payload returned)" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Policy evaluation failed — spend limit exceeded or service class denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/rh/approve": { "post": { "tags": [ "rh" ], "summary": "Approve a pending RH trader run", "description": "Approves a pending Robinhood trade run that was gated by policy and returned 202. Instrument-aware: the payload includes instrument context (type, direction, notional, leverage, liquidation price) so a human or supervisor agent can make an informed decision. Perp and leveraged runs carry a short `expires_at` TTL — approval after expiry returns 410. Requires X-API-Key.", "operationId": "rhApprove", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id" ], "properties": { "run_id": { "type": "string", "description": "UUID of the pending rh-trader run" }, "approved_by": { "type": "string", "description": "User or agent slug approving the run" }, "instrument_type": { "type": "string", "enum": [ "equity", "perp", "crypto", "rwa", "earn", "spend" ], "description": "Asset class of the run being approved — surfaced for UI and audit" }, "direction": { "type": "string", "enum": [ "long", "short", "buy", "sell" ], "description": "Trade direction" }, "notional_usdc": { "type": "number", "description": "Notional position size in USDC" }, "leverage": { "type": "number", "description": "Leverage multiplier (perp only)" }, "liquidation_price": { "type": "number", "description": "Estimated liquidation price (perp only)" }, "policy_verdict": { "type": "string", "enum": [ "requires_human", "borderline", "override" ], "description": "Why this run was gated" }, "expires_at": { "type": "string", "format": "date-time", "description": "Approval window expiry — after this time the run is auto-cancelled. Perp/leveraged runs use a short TTL (minutes); equity runs use 24h." } } } } } }, "responses": { "200": { "description": "Run approved and queued for execution" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Run already approved or cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "Approval window expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/rh/receipts": { "get": { "tags": [ "rh" ], "summary": "List attestation receipts for RH trader runs", "description": "Returns enriched attestation receipts for Robinhood brokerage trade runs, optionally filtered by run or tenant. Each receipt includes an `instrument_metadata` sub-object with asset-class-specific attestation fields (equity: ticker/order_type/limit_price; perp: leverage/notional/liquidation_price/direction; earn: yield_rate/lock_period/principal; rwa: underlying_asset/token_contract/settlement_lag). Requires X-API-Key.", "operationId": "getRhReceipts", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "run_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by run UUID" }, { "name": "tenant_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by tenant slug" }, { "name": "instrument_type", "in": "query", "schema": { "type": "string", "enum": [ "equity", "perp", "crypto", "rwa", "earn", "spend" ] }, "description": "Filter by asset class" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Array of enriched attestation receipt objects", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RhReceipt" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/rh/receipts/{id}": { "get": { "tags": [ "rh" ], "summary": "Get a single attestation receipt", "description": "Returns a single enriched attestation receipt by its UUID. Includes full `instrument_metadata` sub-object. Requires X-API-Key.", "operationId": "getRhReceiptById", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Receipt UUID" } ], "responses": { "200": { "description": "Single attestation receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RhReceipt" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Receipt not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/run": { "post": { "tags": [ "Execution", "Routing" ], "summary": "Run orchestrated paid task", "description": "Primary router-first paid endpoint. Accepts a task plus optional routing preferences or an explicit agent override, then bundles routing, memory, execution, receipt creation, verification, pricing, and x402 settlement into one paid work unit. Optionally supply X-API-Key or a Supabase session to associate the run with a tenant for per-tenant governance, budgets, and policy evaluation.", "operationId": "runTask", "security": [ {}, { "ApiKeyAuth": [] } ], "x-402-price": "dynamic", "x-402-currency": "USDC", "x-402-network": "eip155:8453", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunRequest" } } } }, "responses": { "200": { "description": "Successful paid orchestrated run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunSuccessResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required for orchestrated run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequiredResponse" } } } }, "429": { "description": "Budget or policy limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Run failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunErrorResponse" } } } } } } }, "/api/loop": { "post": { "tags": [ "Execution" ], "summary": "Execute lower-level paid loop", "description": "/api/run is the recommended production entry point.", "operationId": "executeLoop", "security": [ {}, { "ApiKeyAuth": [] } ], "x-402-price": "0.005+", "x-402-currency": "USDC", "x-402-network": "eip155:8453", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopRequest" } } } }, "responses": { "200": { "description": "Successful loop execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopSuccessResponse" } } } }, "402": { "description": "Payment Required (x402)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyPaymentRequiredResponse" } } } } } } }, "/api/loops": { "get": { "tags": [ "Proof" ], "summary": "List recent loops", "description": "Returns recent loop receipts. Guests (no API key, no session) receive an empty list rather than an error.", "operationId": "getRecentLoops", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "session_id", "in": "query", "schema": { "type": "string" } }, { "name": "since", "in": "query", "schema": { "type": "integer" }, "description": "Epoch ms cutoff" } ], "responses": { "200": { "description": "Recent loop history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecentLoopsResponse" } } } } } } }, "/api/policies": { "get": { "tags": [ "Control" ], "summary": "List policies", "description": "Returns every policy for the authenticated tenant. Requires X-API-Key or Supabase session.", "operationId": "listPolicies", "security": [ {}, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Policy list", "content": { "application/json": { "schema": { "type": "object", "properties": { "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Control" ], "summary": "Create a policy", "description": "Accepts either a legacy {name, rules} shape, or a spend-policy shape ({identity_type, api_key|agent_id, audit_trail_required, mode, constraints}). Requires X-API-Key or Supabase session.", "operationId": "createPolicy", "security": [ {}, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" } } } }, "responses": { "201": { "description": "Policy created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/webhooks": { "get": { "tags": [ "Control" ], "summary": "List webhook subscriptions", "operationId": "listWebhooks", "security": [ {}, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Subscription list", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } } } } } } } } }, "post": { "tags": [ "Control" ], "summary": "Create a webhook subscription", "description": "Returns the created subscription plus a one-time signingSecret (not stored in plaintext after this).", "operationId": "createWebhook", "security": [ {}, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Subscription created" }, "400": { "description": "Invalid request" } } } }, "/api/webhooks/{id}": { "patch": { "tags": [ "Control" ], "summary": "Update a webhook subscription", "operationId": "updateWebhook", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "is_active": { "type": "boolean" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Updated subscription" } } }, "delete": { "tags": [ "Control" ], "summary": "Delete a webhook subscription", "operationId": "deleteWebhook", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted" } } } }, "/api/me": { "get": { "tags": [ "Discovery" ], "summary": "Get the authenticated caller’s identity", "description": "Returns orgId, email, and plan for the current Supabase session. Used by the dashboard to bootstrap tenant-scoped UI.", "operationId": "getMe", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } } }, "401": { "description": "Unauthorized" } } } }, "/api/me/plan": { "get": { "tags": [ "Discovery" ], "summary": "Get the authenticated caller’s plan features", "operationId": "getMePlan", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Plan features" }, "401": { "description": "Unauthorized" } } } }, "/api/predictive/alerts": { "get": { "tags": [ "Control" ], "summary": "List predictive alerts", "description": "Risk Pro + Predictive plan feature. Requires X-API-Key or Supabase session.", "operationId": "listPredictiveAlerts", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "severity", "in": "query", "schema": { "type": "string", "enum": [ "critical", "warning", "info" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Alert list" }, "401": { "description": "Unauthorized" }, "403": { "description": "Plan does not include predictive alerts" } } }, "post": { "tags": [ "Control" ], "summary": "Create a predictive alert", "operationId": "createPredictiveAlert", "security": [ {}, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "severity", "type", "message" ], "properties": { "severity": { "type": "string" }, "type": { "type": "string" }, "message": { "type": "string" } } } } } }, "responses": { "201": { "description": "Alert created" } } }, "patch": { "tags": [ "Control" ], "summary": "Mark a predictive alert as read", "operationId": "markPredictiveAlertRead", "security": [ {}, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Marked read" }, "404": { "description": "Alert not found" } } } }, "/api/billing/portal": { "post": { "tags": [ "Control" ], "summary": "Create a Stripe billing portal session", "description": "Requires an authenticated Supabase session.", "operationId": "createBillingPortalSession", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Portal URL" }, "401": { "description": "Unauthorized" }, "404": { "description": "No Stripe customer on record" } } } }, "/api/billing/plan": { "get": { "tags": [ "Control" ], "summary": "Get billing plan and status", "operationId": "getBillingPlan", "parameters": [ { "name": "x-tenant-id", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Plan details" } } } }, "/api/runs": { "get": { "tags": [ "Proof" ], "summary": "List agent runs", "description": "Paginated list of agent runs for the authenticated tenant. Requires X-API-Key or Supabase session.", "operationId": "listRuns", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Cursor: last run id from previous page" }, { "name": "outcome", "in": "query", "schema": { "type": "string", "enum": [ "completed", "blocked", "pending", "approved", "escalated" ] } }, { "name": "action", "in": "query", "schema": { "type": "string" } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Run list" }, "401": { "description": "Unauthorized" } } } }, "/api/cb/receipts": { "get": { "tags": [ "Admin" ], "summary": "List Coinbase brokerage receipts and accounts", "description": "Requires X-Admin-Key. status=pending|history filters cb_trade_receipts; type=accounts returns the cb_accounts snapshot instead.", "operationId": "getCbReceipts", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "history" ] } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "accounts" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Receipts or accounts array" }, "401": { "description": "Unauthorized" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "redis": { "type": "string" }, "supabase": { "type": "string" } } }, "CapabilitiesResponse": { "type": "object", "properties": { "product_layers": { "type": "array", "items": { "type": "string" } }, "free_endpoints": { "type": "array", "items": { "type": "string" } }, "paid_endpoints": { "type": "array", "items": { "type": "string" } } } }, "PricingSurfaceResponse": { "type": "object", "properties": { "lanes": { "type": "array", "items": { "type": "object" } } } }, "ProvidersResponse": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object" } } } }, "RouteRequest": { "type": "object", "required": [ "task" ], "properties": { "task": { "type": "string" }, "budget_usdc": { "type": "number" }, "preferred_lane": { "type": "string" } } }, "RouteRecommendationResponse": { "type": "object", "properties": { "recommended_lane": { "type": "string" }, "estimated_cost_usdc": { "type": "number" }, "reasoning": { "type": "string" } } }, "AuthorizeRequest": { "type": "object", "required": [ "agent_id", "amount_usdc", "merchant" ], "properties": { "agent_id": { "type": "string" }, "amount_usdc": { "type": "number" }, "merchant": { "type": "string" }, "ttl_seconds": { "type": "integer" } } }, "AuthorizeResponse": { "type": "object", "properties": { "authorization_id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } }, "ApprovalsListResponse": { "type": "object", "properties": { "approvals": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } } }, "ApprovalResolutionRequest": { "type": "object", "required": [ "approval_id", "decision" ], "properties": { "approval_id": { "type": "string" }, "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "reason": { "type": "string" } } }, "ApprovalResolutionResponse": { "type": "object", "properties": { "approval_id": { "type": "string" }, "status": { "type": "string" }, "resolved_at": { "type": "string", "format": "date-time" } } }, "BudgetConfigResponse": { "type": "object", "properties": { "daily_limit_usdc": { "type": "number" }, "per_run_limit_usdc": { "type": "number" }, "monthly_limit_usdc": { "type": "number" } } }, "BudgetUpdateRequest": { "type": "object", "properties": { "daily_limit_usdc": { "type": "number" }, "per_run_limit_usdc": { "type": "number" }, "monthly_limit_usdc": { "type": "number" } } }, "RhReceipt": { "type": "object", "properties": { "receipt_id": { "type": "string" }, "run_id": { "type": "string" }, "tenant_id": { "type": "string" }, "instrument_type": { "type": "string", "enum": [ "equity", "perp", "crypto", "rwa", "earn", "spend" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "settled", "failed" ] }, "attestation_hash": { "type": "string", "description": "Keccak-256 hash of the canonical receipt payload, written to Base (eip155:8453)" }, "created_at": { "type": "string", "format": "date-time" }, "instrument_metadata": { "type": "object", "description": "Asset-class-specific attestation fields. Only the fields relevant to instrument_type are populated.", "properties": { "ticker": { "type": "string", "description": "Equity/crypto: ticker symbol" }, "order_type": { "type": "string", "enum": [ "market", "limit", "stop" ], "description": "Equity: order type" }, "limit_price": { "type": "number", "description": "Equity: limit price at time of order" }, "market_condition_flag": { "type": "string", "description": "Equity: market condition note (e.g. pre-market, halt)" }, "leverage_used": { "type": "number", "description": "Perp: actual leverage used" }, "notional_value": { "type": "number", "description": "Perp/RWA: notional position value in USDC" }, "liquidation_price": { "type": "number", "description": "Perp: liquidation price at time of attestation" }, "direction": { "type": "string", "enum": [ "long", "short" ], "description": "Perp: trade direction" }, "yield_rate_at_execution": { "type": "number", "description": "Earn: APY locked at time of deposit decision" }, "lock_period_days": { "type": "integer", "description": "Earn: lock period in days" }, "principal_usdc": { "type": "number", "description": "Earn: principal deposited in USDC" }, "program_id": { "type": "string", "description": "Earn: Robinhood Earn program identifier" }, "underlying_asset": { "type": "string", "description": "RWA/Stock Token: underlying real-world asset name" }, "token_contract_address": { "type": "string", "description": "RWA/Stock Token: ERC-20 contract address on RH Chain (eip155:4663)" }, "settlement_lag_hours": { "type": "integer", "description": "RWA: settlement delay in hours" }, "jurisdiction": { "type": "string", "description": "RWA: KYC jurisdiction code (ISO 3166-1 alpha-2)" } } } } }, "VerificationResult": { "type": "object", "properties": { "verification_id": { "type": "string" }, "verified": { "type": "boolean" }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, "grade": { "type": "string" }, "output_hash": { "type": "string" } }, "required": [ "verified", "score" ], "additionalProperties": true }, "RunRequest": { "type": "object", "properties": { "session_id": { "type": "string" }, "task": { "type": "string" }, "intent": { "type": "string", "description": "Natural language intent — alternative to 'task', preferred for domain-routed calls." }, "agent_id": { "type": "string" }, "preferred_agent_id": { "type": "string" }, "constraints": { "type": "object", "additionalProperties": true }, "context": { "type": "object", "additionalProperties": true }, "options": { "type": "object", "properties": { "include_memory": { "type": "boolean" }, "write_memory": { "type": "boolean" }, "verify": { "type": "boolean" } }, "additionalProperties": true } }, "required": [], "additionalProperties": true }, "RunSuccessResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "paid": { "type": "boolean" }, "run_id": { "type": "string" }, "loop_id": { "type": "string" }, "session_id": { "type": "string" }, "agent_id": { "type": "string" }, "routed": { "type": "boolean" }, "output": { "type": "string" }, "receipt_url": { "type": "string" }, "verification": { "$ref": "#/components/schemas/VerificationResult" }, "cost": { "type": "string" }, "price_usdc": { "type": "number" }, "pricing": { "type": "object", "additionalProperties": true }, "memory": { "type": "object", "additionalProperties": true }, "transaction": { "type": "string" }, "network": { "type": "string" }, "settlement": { "type": "object", "additionalProperties": true }, "retry": { "type": "object", "additionalProperties": true } }, "required": [ "status", "paid", "run_id", "output" ], "additionalProperties": true }, "RunErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "string" }, "message": { "type": "string" }, "run_id": { "type": "string" } }, "required": [ "status", "error", "message" ], "additionalProperties": true }, "X402PaymentRequiredResponse": { "type": "object", "properties": { "x402Version": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "resource": { "type": "object", "additionalProperties": true }, "accepts": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "x402Version", "error", "accepts" ], "additionalProperties": true }, "LegacyPaymentRequiredResponse": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "accepts": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "error" ], "additionalProperties": true }, "LoopRequest": { "type": "object", "properties": { "session_id": { "type": "string" }, "input": { "type": "string" }, "agent_id": { "type": "string" } }, "required": [ "input" ], "additionalProperties": true }, "LoopSuccessResponse": { "type": "object", "properties": { "status": { "type": "string" }, "loop_id": { "type": "string" }, "output": { "type": "string" }, "agent_id": { "type": "string" }, "receipt_url": { "type": "string" } }, "required": [ "status", "loop_id", "output" ], "additionalProperties": true }, "RecentLoopsResponse": { "type": "object", "properties": { "loops": { "type": "array", "items": { "type": "object", "properties": { "loop_id": { "type": "string" }, "agent_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "receipt_url": { "type": "string" } }, "required": [ "loop_id" ], "additionalProperties": true } } }, "required": [ "loops" ], "additionalProperties": true }, "Policy": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "identity_type": { "type": "string", "enum": [ "api_key", "wallet" ] }, "identity_value": { "type": "string" }, "audit_trail_required": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "enforce", "observe" ] }, "constraints": { "type": "object", "properties": { "per_run_cap_usd": { "type": "number" }, "daily_cap_usd": { "type": "number" }, "monthly_cap_usd": { "type": "number" }, "approval_above_usd": { "type": "number" }, "new_vendor_approval": { "type": "boolean" }, "block_on_budget_exceeded": { "type": "boolean" }, "max_parallel_runs": { "type": "integer" }, "allowed_models": { "type": "array", "items": { "type": "string" } }, "blocked_models": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } }, "WebhookSubscription": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "MeResponse": { "type": "object", "properties": { "orgId": { "type": "string" }, "email": { "type": "string" }, "plan": { "type": "string" } } } } } }