Quickstart

Before you start

You need an Attestify OS API key (atst_…). Get one at /onboarding in under a minute. Once you have a key, add it as X-API-Key on every request to POST /api/run.

1. Pick a lane

Every request goes through POST /api/run. You can let the router choose the agent, or you can steer it.

2. Make your first request

Copy this curl command, replace YOUR_KEY with your atst_… key, and run it:

curl -X POST https://attestify-os.vercel.app/api/run \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{
    "type": "http",
    "method": "POST",
    "input": {
      "sessionid": "quickstart-001",
      "task": "Tell me a short joke about software developers.",
      "agentid": "comedian-v1",
      "options": {
        "includememory": false,
        "writememory": false,
        "verify": true
      },
      "idempotencykey": "idem-quickstart-001"
    }
  }'

3. Read the response

A successful paid run returns a structured receipt. Here is what to look for:

{
  "loop_id": "loop_abc123",
  "status": "completed",
  "agent_id": "comedian-v1",
  "result": { "output": "Why do developers prefer dark mode? Because light attracts bugs." },
  "pricing": {
    "priceusdc": "0.0020",
    "baseagentpriceusdc": "0.0015",
    "orchestrationpriceusdc": "0.0005",
    "currency": "USDC"
  },
  "receipt": {
    "loop_id": "loop_abc123",
    "paid": true,
    "amount_usdc": "0.0020",
    "timestamp": "2025-01-15T10:30:00Z"
  },
  "verification": {
    "verified": true,
    "score": 0.87,
    "grade": "B"
  },
  "receipt_url": "https://attestify-os.vercel.app/receipts/loop_abc123"
}

4. Verify it worked

• status: "completed" — the task finished.
• receipt.paid: true — the payment settled.
• verification.verified: true — the run passed the quality check.
• receipt_url — public evidence link, visitable in your browser.

5. Check the dashboard

Open /dashboard to see your loop in the live Control Tower view. It shows total runs, paid runs, revenue, success rate, and per-agent performance.

5b. Inspect the router response

When using router-first execution, the response includes a route block:

{
  "route": {
    "selected_agent": "researcher-v2",
    "method": "router",
    "confidence": 0.92,
    "fallback_used": false
  }
}

6. Canonical request shape

This is the full request object shape. Fields marked optional can be omitted.

{
  "type": "http",         // always "http"
  "method": "POST",       // always "POST"
  "input": {
    "sessionid": "",       // your session identifier
    "task": "",            // what you want the agent to do
    "agentid": "",         // optional: pin to a lane directly
    "preferredagentid": "",// optional: soft steer the router
    "budget": {},          // optional: spend controls
    "policy": {},          // optional: governance rules
    "options": {
      "includememory": true,
      "writememory": true,
      "verify": true
    },
    "idempotencykey": ""   // optional: deduplicate retries
  }
}

7. Optional governance inputs

When you want budget and policy controls on top of the cheap first proof, extend input with budget and policy fields:

{
  "type": "http",
  "method": "POST",
  "input": {
    "sessionid": "quickstart-governed-001",
    "task": "Research the latest x402 adoption trends and summarize the major patterns.",
    "preferredagentid": "researcher-v2",
    "budget": {
      "budgetid": "budget-research-monthly",
      "maxpriceusdc": 0.03,
      "softmaxpriceusdc": 0.025,
      "strict": true,
      "currency": "USDC"
    },
    "policy": {
      "policyids": ["policy-research-evidence", "policy-default-governance"],
      "mode": "default"
    },
    "options": {
      "includememory": true,
      "writememory": true,
      "verify": true
    },
    "idempotencykey": "idem-quickstart-governed-001"
  }
}

8. Where to go next