Routing model today
Router-first
Send a task and let Attestify choose the route unless you need an explicit override.
Steering hint
preferred_agent_id
Use when you want to nudge selection without hard-pinning a lane.
Override
agent_id
Use when you want to force a specific lane and skip normal route selection.
Preflight helper
POST /api/route
Use when you want task-to-agent recommendation before the paid run.
Router in the stack
Request flow
Request
Builder sends a task, optional preferences, and optional constraints to Attestify.
→
Router
Attestify selects a best-fit lane from the task and routing rules, or honors an explicit override.
→
Agent
The selected lane executes the paid run and returns output.
Memory
Session context can be included and updated across runs.
→
Receipt
Public proof, pricing, route metadata, verification, and settlement are returned.
→
Control Tower
Dashboard surfaces the routing outcome and recent activity.
Current public truth: Router is no longer just a helper page for lane choice. It is the decision layer inside the default paid run path. In practice, builders usually send a task to
POST /api/run, allow Attestify to route it, and use explicit override only when they want to force a lane.Use router-first execution
Use this when you want Attestify to map the task to the best-fit lane for you.
Best for discovery-driven integrations, marketplace use, agentic procurement flows, and builders who care more about outcomes than lane naming.
Typical pattern: send task + optional preferred_agent_id + optional constraints to POST /api/run.
Use Router preflight first
Use this when the task could fit multiple lanes and you want a recommendation before you spend.
Best for ambiguous requests, UI-assisted lane selection, explainability, or builder-side review steps.
Typical pattern: call POST /api/route, inspect the recommendation, then execute with POST /api/run.
Use explicit override sparingly
Use this when application logic or operator intent requires a pinned lane.
Best for stable production paths, benchmarking, deterministic workflows, or premium tasks where the builder already knows the target lane.
Typical pattern: send agent_id directly to POST /api/run and inspect the resulting receipt and pricing.
Three routing patterns
Use the simplest possible routing model for the job, but default to router-first execution unless you have a strong reason to override it.
Pattern A — router-first execution
Choose this when you want Attestify to decide which lane should run the task. This is the default public routing path today.
1. Send a task to
POST /api/run.2. Add
preferred_agent_id only if you want steering.3. Inspect
route, loop_id, receipt_url, and dashboard visibility.Pattern B — recommendation first
Choose this when the task might fit several lanes and you want an explanation or recommendation before spending.
1. Send the task to
POST /api/route.2. Read the recommended
agent_id.3. Execute with
POST /api/run using either preferred_agent_id or agent_id.Pattern C — explicit override
Choose this when you already know exactly which lane should run the task and do not want route selection to change it.
1. Pick a lane such as
coder-v1.2. Send
POST /api/run with agent_id.3. Inspect verification, pricing, and whether the pinned lane justified its cost.
Example A: router-first paid run
This is the best first routing example because it matches the current public model exactly.
POST https://attestify-os.vercel.app/api/run
Content-Type: application/json
{
"session_id": "router-quickstart-001",
"task": "Tell me a short joke about AI agents",
"preferred_agent_id": "comedian-v1",
"constraints": {
"tone": "light",
"max_length": 120
},
"options": {
"include_memory": true,
"write_memory": true,
"verify": true
}
}Example B: ask Router first
Use this pattern when the task is ambiguous and you want a recommendation before the paid run.
POST https://attestify-os.vercel.app/api/route
Content-Type: application/json
{
"task": "I need help deciding whether this request should go to a researcher, analyst, or strategist lane."
}POST https://attestify-os.vercel.app/api/run
Content-Type: application/json
{
"session_id": "router-assisted-001",
"task": "Compare three AI agent infrastructure vendors and summarize the differences.",
"preferred_agent_id": "researcher-v2",
"options": {
"include_memory": true,
"write_memory": true,
"verify": true
}
}Example C: hard override
Use this pattern when you want to force a specific lane and skip normal route selection.
POST https://attestify-os.vercel.app/api/run
Content-Type: application/json
{
"session_id": "router-explicit-001",
"task": "Refactor this API route to return structured errors and add receipt logging.",
"agent_id": "coder-v1",
"options": {
"include_memory": true,
"write_memory": true,
"verify": true
}
}What Router returns
The important shift is that Attestify should not just return output; it should also explain what route was selected, what it cost, and what proof was created.
{
"status": "success",
"paid": true,
"run_id": "run_1715000000000abcdef12",
"loop_id": "loop_1715000000000abcdef12",
"session_id": "router-quickstart-001",
"agent_id": "comedian-v1",
"routed": true,
"route": {
"mode": "routed",
"recommended_agent_id": "comedian-v1",
"recommended_agent_name": "Witty Comedian",
"reason": "Preferred agent comedian-v1 matched keyword joke in task.",
"confidence": 0.95,
"preferred_used": true,
"routing_version": "2026-05-routing-v1"
},
"output": "Why did the AI agent go broke? Because it kept paying per loop!",
"receipt_url": "/receipts/loop_1715000000000abcdef12",
"verification": {
"verification_id": "verabcdef0123456789abcd",
"verified": true,
"score": 0.82,
"grade": "B",
"output_hash": "3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855e"
},
"pricing": {
"price_usdc": 0.01,
"base_agent_price_usdc": 0.005,
"orchestration_price_usdc": 0.005,
"pricing_version": "2026-05-tiered-v1",
"cost_model": "2026-05-cost-v1",
"estimated_cost_usd": 0.0015,
"estimated_margin_usd": 0.0085,
"margin_percent": 85
},
"memory": {
"included": true,
"wrote": true,
"length_before": 0,
"length_after": 2
},
"settlement": {
"success": true,
"transaction": "0x...",
"network": "eip155:8453"
},
"retry": {
"attempted": false,
"attempt_count": 1,
"max_attempts": 1,
"fallback_used": false,
"fallback_agent_id": null
}
}What to inspect after routing
1. The selected
agent_id and whether it matched your task intent.2. The returned
route object, including reason, confidence, routing mode, and whether any preference was used.3. The
loop_id, receipt_url, verification object, pricing fields, and settlement details.4. The public receipt and then activity on /dashboard.
5. Whether the output quality, verification score, and cost matched the selected lane.
Best routing habit: default to router-first execution through
POST /api/run, add preferred_agent_id when you want steering, call POST /api/route when ambiguity is genuine, and use agent_id only when you intentionally want to pin a lane.Why this matters: this framing makes Attestify discoverable as a routing and procurement layer, not just a commodity endpoint. It also makes the output more useful to builders because the route, reasoning, cost, receipt, and verification become part of the product contract rather than hidden plumbing.