{"openapi":"3.1.0","info":{"title":"Suede AI Agent Studio public agent API","version":"0.3.0","description":"Public catalog, A2A 1.0 HTTP+JSON execution, discovery documents, portable templates, and machine-run endpoints for agents published from Suede AI Agent Studio. Priced live runs use x402; explicit dry-runs and free agents can run without payment.","x-guidance":"Use the concrete paid service routes under /api/agents/<slug>/run when an operation includes x-payment-info. Send the documented JSON input, follow the x402 HTTP 402 challenge, and retry with PAYMENT-SIGNATURE. Use dryRun only for explicitly non-settling previews.","contact":{"name":"Suede AI Agent Studio support","email":"support@suedeai.ai","url":"https://agents.suedeai.ai/contact"}},"servers":[{"url":"https://agents.suedeai.ai"}],"paths":{"/api/mcp":{"post":{"operationId":"callMcpEndpoint","summary":"Call the MCP endpoint (JSON-RPC over HTTP)","description":"Model Context Protocol endpoint exposing the currently eligible published agents returned by tools/list. Company employees, relay-backed services, and agents without an immutable Live deployment are excluded. Priced tools bill pre-funded workspace credit via an Authorization: Bearer workspace-key header (a UUID). Free eligible tools need no key.","parameters":[{"name":"Authorization","in":"header","required":false,"description":"Bearer workspace key (UUID) for priced tool calls.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"JSON-RPC result or tool error."},"202":{"description":"Notification acknowledged."},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Bearer is not a valid workspace key."},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/catalog":{"get":{"operationId":"listPublishedAgents","summary":"List currently published agents","responses":{"200":{"description":"Current public catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/services":{"get":{"operationId":"listCuratedBusinessServices","summary":"List Suede-curated business services","description":"A deliberately small shelf of business decision services with typed input and output schemas, safe examples, pricing facts, and explicit human-review boundaries.","responses":{"200":{"description":"Current curated business service feed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CuratedServiceCatalog"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/.well-known/x402":{"get":{"operationId":"getX402Index","summary":"Read current x402 payment discovery","responses":{"200":{"description":"x402 discovery index for published agents."},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/.well-known/agent-card.json":{"get":{"operationId":"getStudioAgentCard","summary":"Read the root agent and capability card","responses":{"200":{"description":"Current published-agent capability card."},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/a2a":{"get":{"operationId":"getStudioA2aAgentCard","summary":"Read the root A2A 1.0 AgentCard","responses":{"200":{"description":"Aggregate AgentCard advertising the root HTTP+JSON 1.0 interface."},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/a2a/message:send":{"post":{"operationId":"sendStudioA2aMessage","summary":"Route an A2A message to a published agent","description":"A2A 1.0 HTTP+JSON SendMessage router. Set metadata.x-suede.agent to a published agent ID or slug and send that agent's structured input as the message data part. Execution, x402, and AP2 behavior are identical to the selected per-agent interface. Eligible targets can negotiate experimental AP2 v0.2 merchant authorization with A2A-Extensions; x402 v2 remains the settlement rail.","parameters":[{"name":"A2A-Version","in":"header","required":true,"description":"A2A protocol version. This interface supports 1.0.","schema":{"type":"string","const":"1.0"}},{"name":"A2A-Extensions","in":"header","required":false,"description":"Negotiate the advertised experimental AP2 v0.2 merchant extension. In required mode this header and valid mandates are required for priced Live execution.","schema":{"type":"string","const":"https://github.com/google-agentic-commerce/ap2/v1"}},{"name":"X-A2A-Extensions","in":"header","required":false,"deprecated":true,"description":"Temporary sample-client compatibility spelling for A2A-Extensions.","schema":{"type":"string","const":"https://github.com/google-agentic-commerce/ap2/v1"}}],"requestBody":{"required":true,"content":{"application/a2a+json":{"schema":{"$ref":"#/components/schemas/A2ARootSendMessageRequest"}}}},"responses":{"200":{"description":"Direct synchronous A2A message response.","content":{"application/a2a+json":{"schema":{"$ref":"#/components/schemas/A2ASendMessageResponse"}}}},"400":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"402":{"description":"x402 payment required for a priced live call."},"403":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"409":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"410":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"413":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"502":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/agents/{agent}/.well-known/agent-card.json":{"get":{"operationId":"getPublishedAgentCard","summary":"Read one published agent's capability card","parameters":[{"name":"agent","in":"path","required":true,"description":"Published agent slug (preferred canonical identity) or legacy id.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Capability, provider, and pricing details."},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agent}/.well-known/x402":{"get":{"operationId":"getPublishedAgentX402","summary":"Read one published agent's x402 terms","parameters":[{"name":"agent","in":"path","required":true,"description":"Published agent slug (preferred canonical identity) or legacy id.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Current x402 payment requirements."},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agent}/a2a":{"get":{"operationId":"getPublishedAgentA2a","summary":"Read one published agent's A2A 1.0 AgentCard","parameters":[{"name":"agent","in":"path","required":true,"description":"Published agent slug (preferred canonical identity) or legacy id.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"A2A AgentCard advertising an HTTP+JSON 1.0 interface."},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agent}/a2a/message:send":{"post":{"operationId":"sendPublishedAgentA2aMessage","summary":"Execute one published agent via A2A SendMessage","description":"A2A 1.0 HTTP+JSON SendMessage. Send exactly one structured data part containing the agent input object. Returns a direct ROLE_AGENT message. Priced live calls preserve the same x402 HTTP 402 challenge and PAYMENT-SIGNATURE retry as the direct run endpoint. When advertised, experimental AP2 v0.2 merchant authorization is negotiated with A2A-Extensions; x402 v2 remains the settlement rail.","parameters":[{"name":"agent","in":"path","required":true,"description":"Published agent slug (preferred canonical identity) or legacy id.","schema":{"type":"string","minLength":1}},{"name":"A2A-Version","in":"header","required":true,"description":"A2A protocol version. This interface supports 1.0.","schema":{"type":"string","const":"1.0"}},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"Base64-encoded x402 v2 payment payload for a priced live call.","schema":{"type":"string"}},{"name":"A2A-Extensions","in":"header","required":false,"description":"Negotiate the advertised experimental AP2 v0.2 merchant extension. In required mode this header and valid mandates are required for priced Live execution.","schema":{"type":"string","const":"https://github.com/google-agentic-commerce/ap2/v1"}},{"name":"X-A2A-Extensions","in":"header","required":false,"deprecated":true,"description":"Temporary sample-client compatibility spelling for A2A-Extensions.","schema":{"type":"string","const":"https://github.com/google-agentic-commerce/ap2/v1"}}],"requestBody":{"required":true,"content":{"application/a2a+json":{"schema":{"$ref":"#/components/schemas/A2ASendMessageRequest"}}}},"responses":{"200":{"description":"Direct synchronous A2A message response.","content":{"application/a2a+json":{"schema":{"$ref":"#/components/schemas/A2ASendMessageResponse"}}}},"400":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"402":{"description":"x402 payment required for a priced live call."},"403":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"409":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"410":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"413":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"502":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/agents/{agent}/a2a/message:stream":{"post":{"operationId":"streamPublishedAgentA2aMessage","summary":"A2A streaming capability probe","description":"Returns UnsupportedOperation because these synchronous services advertise streaming: false.","parameters":[{"name":"agent","in":"path","required":true,"description":"Published agent slug (preferred canonical identity) or legacy id.","schema":{"type":"string","minLength":1}},{"name":"A2A-Version","in":"header","required":true,"description":"A2A protocol version. This interface supports 1.0.","schema":{"type":"string","const":"1.0"}}],"responses":{"400":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/agents/{agent}/a2a/tasks":{"get":{"operationId":"listPublishedAgentA2aTasks","summary":"List A2A tasks","description":"These services return direct messages and retain no A2A tasks, so the list is empty.","parameters":[{"name":"agent","in":"path","required":true,"description":"Published agent slug (preferred canonical identity) or legacy id.","schema":{"type":"string","minLength":1}},{"name":"A2A-Version","in":"header","required":true,"description":"A2A protocol version. This interface supports 1.0.","schema":{"type":"string","const":"1.0"}}],"responses":{"200":{"description":"Empty direct-message task collection.","content":{"application/a2a+json":{"schema":{"$ref":"#/components/schemas/A2AListTasksResponse"}}}},"400":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/agents/{agent}/a2a/tasks/{taskId}":{"get":{"operationId":"getPublishedAgentA2aTask","summary":"Get an A2A task","description":"Direct-message services do not create tasks and return TaskNotFound.","parameters":[{"name":"agent","in":"path","required":true,"description":"Published agent slug (preferred canonical identity) or legacy id.","schema":{"type":"string","minLength":1}},{"name":"taskId","in":"path","required":true,"description":"Opaque A2A task identifier.","schema":{"type":"string","minLength":1}},{"name":"A2A-Version","in":"header","required":true,"description":"A2A protocol version. This interface supports 1.0.","schema":{"type":"string","const":"1.0"}}],"responses":{"400":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/agents/{agent}/a2a/tasks/{taskId}:cancel":{"post":{"operationId":"cancelPublishedAgentA2aTask","summary":"Cancel an A2A task","description":"Direct-message services do not create tasks and return TaskNotFound.","parameters":[{"name":"agent","in":"path","required":true,"description":"Published agent slug (preferred canonical identity) or legacy id.","schema":{"type":"string","minLength":1}},{"name":"taskId","in":"path","required":true,"description":"Opaque A2A task identifier.","schema":{"type":"string","minLength":1}},{"name":"A2A-Version","in":"header","required":true,"description":"A2A protocol version. This interface supports 1.0.","schema":{"type":"string","const":"1.0"}}],"responses":{"400":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/agents/{agent}/a2a/tasks/{taskId}/pushNotificationConfigs":{"post":{"operationId":"createPublishedAgentA2aPushNotificationConfig","summary":"A2A push-notification capability probe","description":"Returns PushNotificationNotSupported because these services advertise pushNotifications: false.","parameters":[{"name":"agent","in":"path","required":true,"description":"Published agent slug (preferred canonical identity) or legacy id.","schema":{"type":"string","minLength":1}},{"name":"taskId","in":"path","required":true,"description":"Opaque A2A task identifier.","schema":{"type":"string","minLength":1}},{"name":"A2A-Version","in":"header","required":true,"description":"A2A protocol version. This interface supports 1.0.","schema":{"type":"string","const":"1.0"}}],"responses":{"400":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"A2A request failed.","content":{"application/a2a+json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/agents/{agent}/template":{"get":{"operationId":"downloadPublishedAgentTemplate","summary":"Download one published agent's portable template","parameters":[{"name":"agent","in":"path","required":true,"description":"Published agent slug (preferred canonical identity) or legacy id.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Portable flow, run client, and README bundle.","headers":{"Content-Disposition":{"schema":{"type":"string"},"description":"Attachment filename for the JSON bundle."}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agent}/run":{"post":{"operationId":"runPublishedAgent","summary":"Run one published agent","description":"Send an input object. Set dryRun true for the explicit non-settling preview path. A priced live run without a valid PAYMENT-SIGNATURE header responds with HTTP 402 and current x402 v2 payment requirements. Legacy X-PAYMENT remains accepted during migration. When advertised, the ap2 body member presents experimental AP2 v0.2 merchant authorization before x402 settlement.","parameters":[{"name":"agent","in":"path","required":true,"description":"Published agent slug (preferred canonical identity) or legacy id.","schema":{"type":"string","minLength":1}},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"Base64-encoded x402 v2 payment payload for a priced live run.","schema":{"type":"string"}},{"name":"X-PAYMENT","in":"header","required":false,"deprecated":true,"description":"Legacy x402 v1 payment payload accepted during migration.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunRequest"}}}},"responses":{"200":{"description":"Run completed.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RunResult"},{"$ref":"#/components/schemas/ResourceRunEnvelope"}]}}}},"202":{"description":"AP2 authorization or paid relay delivery is still being reconciled; retry after the Retry-After interval."},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Pay with credit needs a signed-in session. No credit was used."},"402":{"description":"Payment required for a priced live run."},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"The retained AP2 response has expired; the authorization stays consumed."},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"AP2 is required: request a merchant checkout and present Checkout and Payment Mandates."},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The agent's relay endpoint failed or reported a failed delivery."},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/po-match-gate-mkgu0/run":{"post":{"operationId":"runPublishedAgent_po_match_gate_mkgu0","summary":"Run PO Match Gate","description":"Compare one purchase order with its invoice. Returns pass or hold, with every quantity, unit-price, vendor, and total discrepancy identified before payment approval. This concrete Live route charges 0.050000 USDC per successful x402-authorized call.","parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"Base64-encoded x402 v2 payment payload returned after satisfying the HTTP 402 challenge.","schema":{"type":"string"}}],"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.050000"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"object","additionalProperties":false,"required":["purchaseOrder","invoice"],"properties":{"purchaseOrder":{"type":"string","minLength":1,"description":"Purchase-order text or structured JSON serialized as text."},"invoice":{"type":"string","minLength":1,"description":"Invoice text or structured JSON serialized as text."}}}},"required":["input"],"additionalProperties":false},"example":{"input":{"purchaseOrder":"PO-9920: 100 widget-A units at $2.50, total $250.00.","invoice":"INV-7781 for PO-9920: 100 widget-A units at $2.65, total $265.00."}}}}},"responses":{"200":{"description":"Run completed after verified x402 settlement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunResult"},"example":{"runId":"run_123","status":"done","totalCostUsdc":0.05,"outputs":{},"result":{"matched":false,"status":"hold","discrepancies":["Unit price is $2.65 on the invoice and $2.50 on the PO; delta $15.00."],"note":"Hold for buyer approval because the invoice exceeds the PO price."},"settled":true}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required; response carries current x402 v2 terms."},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-suede-output-schema":{"type":"object","additionalProperties":false,"required":["matched","status","discrepancies","note"],"properties":{"matched":{"type":"boolean"},"status":{"type":"string","enum":["pass","hold"]},"discrepancies":{"type":"array","description":"Every supported mismatch between the PO and invoice.","items":{"type":"string"}},"note":{"type":"string"}}}}},"/.well-known/ap2.json":{"get":{"operationId":"getAp2MerchantIndex","summary":"Read the experimental AP2 merchant discovery index","responses":{"200":{"description":"Current AP2 merchant profile and eligible published services."},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/.well-known/ap2-jwks.json":{"get":{"operationId":"getAp2MerchantJwks","summary":"Read AP2 merchant Checkout Receipt verification keys","responses":{"200":{"description":"Public ES256 keys for verifying merchant checkout quotes and receipts."},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/.well-known/ap2-trusted-surface-jwks.json":{"get":{"operationId":"getAp2TrustedSurfaceJwks","summary":"Read AP2 Trusted Surface verification keys","responses":{"200":{"description":"Public ES256 keys for verifying Suede-issued direct mandates."},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ap2/authorize":{"get":{"operationId":"openAp2TrustedSurface","summary":"Open the authenticated AP2 payment consent surface","responses":{"200":{"description":"HTML Trusted Surface for checkout review and explicit consent."}}}},"/api/ap2/trusted-surface":{"post":{"operationId":"useAp2TrustedSurface","summary":"Inspect a merchant checkout or issue an explicitly approved direct mandate pair","description":"Same-origin authenticated endpoint. Inspect verifies and returns exact payment terms; authorize binds explicit consent to that checkout hash and payer wallet.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"operation":{"type":"string","const":"inspect"},"checkoutJwt":{"type":"string","minLength":1,"maxLength":32768}},"required":["operation","checkoutJwt"],"additionalProperties":false},{"type":"object","properties":{"operation":{"type":"string","const":"authorize"},"checkoutJwt":{"type":"string","minLength":1,"maxLength":32768},"payerAddress":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"consent":{"type":"object","properties":{"accepted":{"type":"boolean","const":true},"checkoutHash":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"}},"required":["accepted","checkoutHash"],"additionalProperties":false}},"required":["operation","checkoutJwt","payerAddress","consent"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"Verified checkout summary or signed direct mandate pair."},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agent}/.well-known/ap2":{"get":{"operationId":"getPublishedAgentAp2","summary":"Read one published service's experimental AP2 terms","parameters":[{"name":"agent","in":"path","required":true,"description":"Published agent slug (preferred canonical identity) or legacy id.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Merchant authorization, checkout, receipt, and x402 binding metadata."},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agent}/ap2/checkout":{"post":{"operationId":"issuePublishedAgentAp2Checkout","summary":"Request a merchant-signed AP2 checkout quote","description":"Runs the same company, input, payout, and immutable Live-deployment preflight as execution, then returns a short-lived signed checkout JWT without settling or running the service.","parameters":[{"name":"agent","in":"path","required":true,"description":"Published agent slug (preferred canonical identity) or legacy id.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"object","additionalProperties":true},"runVariables":{"type":"object","additionalProperties":true}},"additionalProperties":false}}}},"responses":{"200":{"description":"Merchant-signed AP2 checkout quote and exact x402 payment terms."},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"],"additionalProperties":true},"Catalog":{"type":"object","properties":{"service":{"type":"string"},"description":{"type":"string"},"site":{"type":"string","format":"uri"},"count":{"type":"integer","minimum":0},"agents":{"type":"array","items":{"type":"object","properties":{"calls":{"type":["integer","null"],"minimum":0,"description":"Recorded calls; null when usage counts are unavailable."},"settledCalls":{"type":["integer","null"],"minimum":0,"description":"Recorded settled calls; null when usage counts are unavailable."}},"required":["calls","settledCalls"],"additionalProperties":true}}},"required":["service","site","count","agents"]},"CuratedServiceCatalog":{"type":"object","properties":{"service":{"type":"string"},"operator":{"type":"string"},"description":{"type":"string"},"collection":{"type":"string","const":"business-operations"},"site":{"type":"string","format":"uri"},"readinessProjectionVersion":{"type":"integer","const":2},"count":{"type":"integer","minimum":0},"historicallySettledServiceCount":{"type":["integer","null"],"minimum":0,"description":"Services with recorded settled calls; null when any service's usage counts are unavailable."},"services":{"type":"array","items":{"type":"object","properties":{"calls":{"type":["integer","null"],"minimum":0},"settledCalls":{"type":["integer","null"],"minimum":0},"readiness":{"$ref":"#/components/schemas/CuratedServiceReadiness"}},"required":["calls","settledCalls","readiness"],"additionalProperties":true}}},"required":["service","operator","collection","site","readinessProjectionVersion","count","historicallySettledServiceCount","services"],"additionalProperties":false},"CuratedServiceReadiness":{"type":"object","properties":{"state":{"type":"string","enum":["preview","payment-enabled","unavailable"]},"publishedLive":{"type":"boolean"},"acceptsPayment":{"type":"boolean"},"previewAvailable":{"type":"boolean"},"hasSettledCalls":{"type":["boolean","null"],"description":"Historical evidence only: true when this service has at least one recorded settled call; null when usage counts are unavailable. It does not assert current payment readiness."},"settledCalls":{"type":["integer","null"],"minimum":0},"lastCallAt":{"type":["integer","null"],"minimum":0}},"required":["state","publishedLive","acceptsPayment","previewAvailable","hasSettledCalls","settledCalls","lastCallAt"],"additionalProperties":false},"RunRequest":{"type":"object","properties":{"input":{"type":"object","additionalProperties":true},"runVariables":{"type":"object","additionalProperties":true},"dryRun":{"type":"boolean"},"ap2":{"type":"object","properties":{"authorizationMode":{"type":"string","enum":["direct","autonomous"]},"checkoutMandateSdJwt":{"type":"string","minLength":1},"paymentMandateSdJwt":{"type":"string","minLength":1}},"required":["authorizationMode","checkoutMandateSdJwt","paymentMandateSdJwt"],"additionalProperties":false}},"additionalProperties":true},"A2ASendMessageRequest":{"type":"object","properties":{"message":{"type":"object","properties":{"messageId":{"type":"string","minLength":1},"contextId":{"type":"string","minLength":1},"role":{"type":"string","const":"ROLE_USER"},"parts":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true},"mediaType":{"type":"string","const":"application/json"}},"required":["data"],"additionalProperties":true}}},"required":["messageId","role","parts"],"additionalProperties":true}},"required":["message"],"additionalProperties":true,"description":"When AP2 is negotiated, include one business-input data part plus Checkout and Payment Mandate SD-JWT data parts using the advertised AP2 keys."},"A2ARootSendMessageRequest":{"allOf":[{"$ref":"#/components/schemas/A2ASendMessageRequest"},{"type":"object","properties":{"metadata":{"type":"object","properties":{"x-suede":{"type":"object","properties":{"agent":{"type":"string","minLength":1,"maxLength":256}},"required":["agent"],"additionalProperties":true}},"required":["x-suede"],"additionalProperties":true}},"required":["metadata"]}]},"A2ASendMessageResponse":{"type":"object","properties":{"message":{"type":"object","properties":{"messageId":{"type":"string"},"contextId":{"type":"string"},"role":{"type":"string","const":"ROLE_AGENT"},"parts":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":true}},"metadata":{"type":"object","additionalProperties":true}},"required":["messageId","contextId","role","parts"],"additionalProperties":true}},"required":["message"],"additionalProperties":false},"A2AListTasksResponse":{"type":"object","properties":{"tasks":{"type":"array","items":{"type":"object","additionalProperties":true}},"totalSize":{"type":"integer","const":0},"pageSize":{"type":"integer","minimum":1,"maximum":100},"nextPageToken":{"type":"string","const":""}},"required":["tasks","totalSize","pageSize","nextPageToken"],"additionalProperties":false},"RunResult":{"type":"object","properties":{"runId":{"type":"string"},"status":{"type":"string","enum":["done","error"]},"totalCostUsdc":{"type":"number"},"outputs":{"type":"object","additionalProperties":true},"result":{"type":"object","additionalProperties":true,"description":"Best-effort normalized result for a curated service; raw outputs remain available."},"settled":{"type":"boolean"},"relayed":{"type":"boolean"},"transaction":{"type":"string"},"payer":{"type":"string"},"ap2":{"type":"object","properties":{"profile":{"type":"string","const":"ap2-v0.2-experimental"},"authorizationMode":{"type":["string","null"],"enum":["direct","autonomous",null]},"checkoutReceipt":{"type":"string"}},"required":["profile","authorizationMode","checkoutReceipt"],"additionalProperties":false}},"required":["runId","status","totalCostUsdc","outputs","settled"],"additionalProperties":false},"ResourceRunEnvelope":{"type":"object","properties":{"result":{},"resourceReceipt":{"type":"object","properties":{"resourceProductId":{"type":"string"},"resourceVersion":{"type":"string"},"semanticHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"freshness":{"type":"string","enum":["fresh","stale","mixed"]},"evidence":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"sourceSnapshotId":{"type":"string"},"locator":{"type":"string"},"observedAt":{"type":"string","format":"date-time"},"fieldHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"confidence":{"type":"number","minimum":0,"maximum":1},"conflict":{"type":"string"}},"required":["id","sourceSnapshotId","locator","observedAt"],"additionalProperties":false}},"unknowns":{"type":"array","items":{"type":"string"}},"conflicts":{"type":"array","items":{"type":"string"}},"outputSchemaValid":{"type":"boolean","const":true}},"required":["resourceProductId","resourceVersion","semanticHash","freshness","evidence","unknowns","conflicts","outputSchemaValid"],"additionalProperties":false},"payment":{"type":"object","properties":{"priceUsdc":{"type":"number","minimum":0},"state":{"type":"string","enum":["free","challenged","credited","settled","refunded","failed"]},"receiptId":{"type":["string","null"]}},"required":["priceUsdc","state","receiptId"],"additionalProperties":false}},"required":["result","resourceReceipt","payment"],"additionalProperties":false}}},"x-suede-resource-contracts":{"extensionUri":"https://agents.suedeai.ai/extensions/resource/v1","contracts":[]},"x-suede-ap2":{"protocol":"AP2","version":"0.2","profile":"merchant","status":"experimental","mode":"optional","extensionUri":"https://github.com/google-agentic-commerce/ap2/v1","settlementRail":"x402-v2","negotiationHeader":"A2A-Extensions","compatibilityHeader":"X-A2A-Extensions","mandateDataKeys":["ap2.mandates.CheckoutMandateSdJwt","ap2.mandates.PaymentMandateSdJwt"],"merchantReceiptDataKey":"ap2.CheckoutReceipt","sellerSubprofile":{"trustedIssuerAlgorithms":"configured allowlist","rootTrustResolution":"pinned-exact-or-unique-compatible-key","acceptedSdAlgorithms":["sha-256"],"delegatedKey":{"kty":"EC","crv":"P-256","alg":"ES256","kidMember":"optional","algMember":"optional"},"requiredClaims":["iat","exp","aud","nonce"],"autonomousRootRequiredClaims":["iat","exp"],"maximumDelegationHops":1,"supportedCheckoutConstraints":["checkout.allowed_merchants","checkout.line_items"],"supportedPaymentConstraints":["payment.allowed_payees","payment.allowed_payment_instruments","payment.allowed_pisps","payment.amount_range","payment.reference","payment.execution_date"],"unknownConstraints":"rejected","statefulOpenPaymentConstraints":false,"openPaymentPresetClaims":["payee","payment_amount","payment_instrument","pisp","execution_date","risk_data"],"openPaymentPresetRule":"exact-match-closed","paymentInstrumentId":"CAIP-10 eip155:8453:<payer-address>","receiptReferenceRule":"sd-hash-final-sd-jwt"},"trustedSurface":{"issuer":"https://agents.suedeai.ai/ap2/trusted-surface","authorizeUrl":"https://agents.suedeai.ai/ap2/authorize","apiUrl":"https://agents.suedeai.ai/api/ap2/trusted-surface","jwksUrl":"https://agents.suedeai.ai/.well-known/ap2-trusted-surface-jwks.json"},"requiredForPricedLive":false,"documentationUrl":"https://agents.suedeai.ai/docs/payments#ap2"}}