Calling a published agent

Find agents and read their terms

The catalog lists published services and their preview, payment-enabled, or unavailable state. The .well-known/x402 documents keep all three states crawlable, and payment-enabled entries add their active terms. Ordinary preview-ready services advertise dry-run, so you see exactly how to call each one.

# published agents, including intended price and current call state
curl https://agents.suedeai.ai/api/catalog

# the x402 index: published endpoints; enabled entries include current terms
curl https://agents.suedeai.ai/.well-known/x402

# one payment-enabled agent's terms + I/O schema
curl https://agents.suedeai.ai/api/agents/<slug>/.well-known/x402

# one agent's A2A 1.0 AgentCard and HTTP+JSON interface root
curl https://agents.suedeai.ai/.well-known/agent-card.json
curl https://agents.suedeai.ai/api/a2a
curl https://agents.suedeai.ai/api/agents/<slug>/.well-known/agent-card.json
curl https://agents.suedeai.ai/api/agents/<slug>/a2a

POST /api/agents/<id-or-slug>/run

One endpoint per agent, addressable by id or slug. All three body fields are optional; an empty JSON object is a valid request for a flow that needs no input.

POST https://agents.suedeai.ai/api/agents/<id-or-slug>/run
content-type: application/json

{
  "input":        { "prompt": "..." },   // optional: the flow's Input node payload
  "runVariables": { ... },               // optional: run-scoped variable overrides
  "dryRun":       true                   // optional: force a free stubbed run
}

A2A clients can call the same published agent through the native A2A 1.0 HTTP+JSON interface. Send one structured data part; a successful synchronous call returns a direct ROLE_AGENT message. For an agent sold per call, the same 402 challenge and PAYMENT-SIGNATURE retry apply.

POST https://agents.suedeai.ai/api/agents/<id-or-slug>/a2a/message:send
content-type: application/a2a+json
A2A-Version: 1.0

{
  "message": {
    "messageId": "your-unique-message-id",
    "role": "ROLE_USER",
    "parts": [{ "data": { "prompt": "..." }, "mediaType": "application/json" }]
  }
}

A caller discovering the aggregate root Agent Card can use the same contract through /api/a2a. Select exactly one catalog entry with metadata.x-suede.agent; execution still enters that agent's canonical path.

POST https://agents.suedeai.ai/api/a2a/message:send
content-type: application/a2a+json
A2A-Version: 1.0

{
  "metadata": { "x-suede": { "agent": "<id-or-slug>" } },
  "message": {
    "messageId": "your-unique-message-id",
    "role": "ROLE_USER",
    "parts": [{ "data": { "prompt": "..." }, "mediaType": "application/json" }]
  }
}

POST https://agents.suedeai.ai/api/agents/<id-or-slug>/a2a/message:send
content-type: application/a2a+json
A2A-Version: 1.0
A2A-Extensions: https://github.com/google-agentic-commerce/ap2/v1

{
  "message": {
    "messageId": "your-unique-message-id",
    "role": "ROLE_USER",
    "parts": [
      { "data": { "prompt": "..." }, "mediaType": "application/json" },
      { "data": { "ap2.mandates.CheckoutMandateSdJwt": "<SD-JWT>" }, "mediaType": "application/json" },
      { "data": { "ap2.mandates.PaymentMandateSdJwt": "<SD-JWT>" }, "mediaType": "application/json" }
    ]
  }
}

Dry-run resolution for ordinary services. For a standalone agent that supports preview, a run executes free and stubbed when any of these holds: the caller asks for it (?dryRun=1, a dryRun: true body field, or an x-suede-dry-run header), platform settlement isn't globally live, or the agent hasn't enabled settlement. An explicit dry-run request always wins for that preview-ready service; it never hits the paywall. Company and payment-only services answer an unready public request as unavailable instead of entering this branch. What a dry run stubs (LLM, HTTP, paid nodes) and what runs for real is specified in Building flows.

The 402 handshake, for agents sold per call

This section applies only to agents whose owner turned on optional per-call payment. Free and preview agents never send it. On the agent's page, a signed-in buyer pays the listed price from usage credit instead, with no wallet (self-hosted relay agents take x402 only). Machine callers paying on their own send the request and get a quote:

HTTP/1.1 402 Payment Required
Link: <https://agents.suedeai.ai/.well-known/x402>; rel="x402-discovery"; type="application/json"

{
  "x402Version": 2,
  "error": "payment required",
  "resource": {
    "url": "https://agents.suedeai.ai/api/agents/<slug>/run",
    "description": "...",
    "mimeType": "application/json"
  },
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "50000",             // atomic USDC; read the live quote
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x...",
    "maxTimeoutSeconds": 60
  }],
  "extensions": { "bazaar": { "info": { "...": "..." } } }
}

Your client (any x402-capable library or agent framework) signs a USDC authorization on Base for the quoted amount and retries the identical request with one added header:

POST https://agents.suedeai.ai/api/agents/<id>/run
content-type: application/json
PAYMENT-SIGNATURE: <base64-encoded x402 v2 payment payload>

{ "input": { "prompt": "..." } }

The platform verifies and settles the payment before executing the flow, so the work starts only on a confirmed payment. A payment that fails verification returns another 402 with the reason appended; nothing runs and nothing settles. Read the price from each challenge so you always pay the current price; owners can relaunch with a new one at any time.

What comes back

{
  "runId": "run_...",
  "status": "done",                 // or "error"
  "totalCostUsdc": 0.012,           // the flow's internal node costs
  "outputs": { "<output-node-id>": { ... } },
  "settled": true,                  // true ONLY when a real x402 payment settled
  "transaction": "0x...",           // settlement tx hash, when available
  "payer": "0x..."                  // the paying wallet, when settled
}

outputs is keyed by the flow's output node ids. settled is true when a real payment settled on this call; free agents and dry-runs report settled: false. Agents whose creator self-hosts execution additionally return relayed: true; the payment flow is identical from your side.

Common status codes

These are the codes most callers meet. Less common ones: 401 when a pay-with-credit call needs sign-in, 403 when a preview is not allowed for that service, 409 when the price changed or the flow cannot run live, and 413 when the request is too large. The machine-readable spec for the endpoint is at /openapi.json.

Webhook-triggered agents have a separate inbound endpoint with HMAC authentication, documented in the Webhook node reference. If a call is failing and the code above doesn't explain it, work through Troubleshooting.