API Reference

// 00 · Agent-native registration

Agents with a Stripe Link Agent Wallet can self-register and submit their first task in two API calls — no human, no email, no dashboard. Hit POST /api/public/register with an SPT to receive an api_key, then submit tasks like any other developer.

// request

curl -X POST https://getcallable.dev/api/public/register \
  -H "Content-Type: application/json" \
  -d '{
    "payment_credential": {
      "type": "spt",
      "spt": "spt_1Abc..."
    },
    "agent_name": "Acme Booking Agent"
  }'

// response

{
  "api_key": "callable_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "message": "Agent registered. Use this api_key as x-api-key header in all future requests."
}

The endpoint is unauthenticated — no API key required to call it. Agents can also pay per-task without registering a saved card: include payment_credential in the body of POST /tasks and that credential is used instead of any card on file.

// 00b · Feedback API

Agents can request new task types programmatically by calling POST /api/public/feedback. This is how Callable grows — agent-driven product development. We review every submission weekly and ship the most-requested types fast.

Auth is optional: include your x-api-key header to link the request to your developer account, or call anonymously.

curl -X POST https://getcallable.dev/api/public/feedback \
  -H "Content-Type: application/json" \
  -H "x-api-key: callable_live_..." \
  -d '{
    "description": "Our agent needs to schedule dentist appointments by phone with insurance verification.",
    "category": "Phone/voice",
    "urgency": "important"
  }'

{
  "status": "received",
  "message": "Feedback submitted. We review all requests weekly and build fast.",
  "request_id": "uuid"
}

When POST /tasks is called with a task_type we don't support, the response includes the list of supported types and a pointer back to this endpoint — so agents can self-discover and request new capabilities in the same loop.

// 01 · Authentication

Every request to the Callable API must include your API key in the X-API-Key header. Requests without a valid key return 401 Unauthorized.

X-API-Key: your_api_key

// 02 · POST /tasks

Submit a task for expert execution. Returns a task_id and an initial status of pending.

// example request

POST https://api.getcallable.dev/tasks HTTP/1.1
X-API-Key: your_api_key
Content-Type: application/json

{
  "task_type": "account_verification",
  "instructions": {
    "platform": "gmail",
    "url": "https://accounts.google.com",
    "credentials": "email + password provided in vault",
    "what_to_verify": "Confirm sign-in works and 2FA prompt appears",
    "screenshot_required": true
  },
  "deadline_minutes": 30,
  "callback_url": "https://agent.example.com/hook"
}

// example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "task_id": "tsk_01HXYZ...",
  "status": "pending",
  "payment": "confirmed"
}

// 03 · Task types

• account_verification

  KYC checks, platform sign-ins, CAPTCHAs, and identity confirmation handled by a real human — returned as structured JSON with screenshot proof.

// 04 · Payments

Every POST /tasks charges synchronously. There is no Checkout redirect — the API responds with payment: "confirmed" once the funds are captured. Two payment paths are supported:

// agent-native — Link Agent Wallet (MPP)

Agents include a payment_credential in the request body containing a Stripe Shared Payment Token (SPT) minted by their Link Agent Wallet. Callable creates a Stripe PaymentIntent with that token via the Machine Payments Protocol — no browser, no redirect, no human in the loop.

{
  "task_type": "account_verification",
  "instructions": { "...": "..." },
  "payment_credential": {
    "type": "spt",
    "spt": "spt_1Abc..."
  }
}

curl -X POST https://getcallable.dev/api/public/tasks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "account_verification",
    "payment_credential": "spt_xxx",
    "deadline_minutes": 30,
    "instructions": {
      "platform": "gmail",
      "url": "https://accounts.google.com",
      "credentials": "email + password in vault",
      "what_to_verify": "Confirm sign-in works and 2FA prompt appears",
      "screenshot_required": true
    }
  }'

Provision an SPT with npx @stripe/link-cli spend-request create. x402 USDC credentials (type: "x402_usdc") are accepted by the schema and reserved for the next release.

// developer fallback — saved card

When payment_credential is omitted, Callable charges the card you saved on your developer account. Add one once at /dashboard — every subsequent request charges the same card off-session.

// 402 challenge

If neither a credential nor a saved card is available, the API returns 402 Payment Required with an x402-style challenge so wallet-equipped agents can retry automatically.

{
  "error": "Payment required",
  "payment": "required",
  "challenge": {
    "scheme": "mpp/stripe",
    "version": "1",
    "accepts": [
      { "credential_type": "shared_payment_token", "network": "stripe" },
      { "credential_type": "x402_usdc", "network": "base" }
    ],
    "amount": 49,
    "currency": "usd"
  }
}

// 05 · Webhooks

When a task transitions to completed, Callable can deliver the result to a callback_url you provide. The payload contains the original task_id, the final status, and a result object specific to the task type.

{
  "task_id": "tsk_01HXYZ...",
  "status": "completed",
  "result": { "...": "..." }
}