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.

X-API-Key: atst_…
Content-Type: application/json

1. Pick a lane

Every request goes through POST /api/run. You can let the router choose the lane, 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 '{
    "session_id": "quickstart-001",
    "intent": "Tell me a short joke about software developers.",
    "lane_id": "comedian-v1",
    "options": {
      "include_memory": false,
      "write_memory": false,
      "verify": true
    },
    "idempotency_key": "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",
  "run_id": "run_abc123",
  "status": "success",
  "execution_status": "completed",
  "lane_id": "comedian-v1",
  "agent_id": "comedian-v1",
  "result": { "output": "Why do developers prefer dark mode? Because light attracts bugs." },
  "pricing": {
    "price_usdc": 0.010,
    "base_lane_price_usdc": 0.005,
    "orchestration_price_usdc": 0.005
  },
  "receipt": {
    "loop_id": "loop_abc123",
    "lane_id": "comedian-v1",
    "settled": true,
    "price_usdc": 0.010,
    "tx_hash": "0x33e8a84c..."
  },
  "verification": { "verified": true, "score": 0.82, "grade": "A" },
  "settlement": { "success": true, "transaction": "0x33e8a84c...", "network": "eip155:8453" }
}

4. Verify it worked

• execution_status: "completed" — the task finished.
• receipt.settled: true — the payment settled.
• verification.verified: true — the run passed the quality check.
• settlement.transaction — on-chain tx hash, verifiable on Basescan.

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-lane performance.

6. Inspect the router response

When using router-first execution (no explicit lane_id), the response includes a routing block:

{
  "routing": {
    "mode": "semantic",
    "recommended_agent_id": "researcher-v2",
    "reason": "Semantic match: researcher-v2 (score=0.612)",
    "confidence": 0.92,
    "preferred_used": false,
    "routing_version": "2026-06-routing-v2"
  }
}

7. Canonical request shape

This is the full request object shape sent directly as the POST body. All fields use snake_case. Fields marked optional can be omitted.

{
  "session_id": "",             // your session identifier
  "intent": "",                 // what you want the lane to do (preferred field)
  "task": "",                   // alias for intent — either works
  "lane_id": "",                // optional: pin to a specific lane directly
  "preferences": {
    "preferred_lane_id": ""     // optional: soft-steer the router without pinning
  },
  "constraints": {
    "max_cost_usdc": 0.05,      // optional: reject if lane price exceeds this
    "priority": "quality"       // optional: "quality" | "speed" | "cost"
  },
  "options": {
    "include_memory": true,
    "write_memory": true,
    "verify": true,
    "webhook_url": ""           // optional: POST receipt to this URL after run
  },
  "idempotency_key": ""         // optional: deduplicate retries
}

8. Optional governance inputs

When you want budget and policy controls, extend the request body with the governance block:

{
  "session_id": "my-session",
  "intent": "Analyse Q2 revenue trends.",
  "preferences": { "preferred_lane_id": "analyst-v1" },
  "constraints": {
    "max_cost_usdc": 0.05,
    "priority": "quality"
  },
  "options": {
    "include_memory": true,
    "write_memory": true,
    "verify": true
  }
}