Default path
/api/run
The main hosted entry point for router-first paid execution.
Pricing model
Base + orchestration
Paid run price combines lane base price and orchestration fee.
Governance inputs
Budgets + policies
Control whether a run proceeds, warns, downgrades, or is blocked.
Audit surfaces
Receipts + evidence
Inspect what was routed, charged, enforced, and settled.
Recommended reading order: get your API key at /onboarding first, then understand router-first execution, pricing, governance, receipts and evidence, and finally use the endpoint index for implementation details.
Important default: public guidance should stay centered on
POST /api/run. Lower-level surfaces like POST /api/loop are useful, but they are not the main first-run integration path.Router-first execution
The core Attestify OS mental model is simple: send a task, let the router select or confirm the agent lane, evaluate governance, execute the work, settle payment, and return structured evidence around what happened.
POST /api/run
Content-Type: application/json
X-API-Key: atst_your_key_here
{
"session_id": "docs-page-001",
"task": "Research the latest x402 adoption trends and summarize the major patterns.",
"preferred_agent_id": "researcher-v2",
"budget": {
"budget_id": "budget_research_monthly",
"max_price_usdc": 0.03,
"soft_max_price_usdc": 0.025,
"strict": true,
"currency": "USDC"
},
"policy": {
"policy_ids": ["policy_research_evidence", "policy_default_governance"],
"mode": "default"
},
"options": {
"include_memory": true,
"write_memory": true,
"verify": true
},
"idempotency_key": "idem-docs-page-001"
}Pricing and paid runs
Hosted pricing should be understood at the paid run level. The final charged amount is the selected lane base price plus the orchestration fee, and the definitive charged value appears in the returned pricing block from a paid run.
paid_run_price_usdc = base_agent_price_usdc + orchestration_price_usdc Example: researcher-v2 = 0.025 + 0.005 = 0.030 USDC
{
"pricing": {
"price_usdc": 0.03,
"base_agent_price_usdc": 0.025,
"orchestration_price_usdc": 0.005,
"pricing_version": "2026-05-tiered-v1",
"cost_model": "2026-05-cost-v1"
}
}Budgets and policies
Governance is part of the execution flow, not a separate afterthought. Budget and policy inputs can allow, warn, downgrade, or block execution, and the result is reflected in the response through fields like budget_outcome and policy_applied.
Budget outcome
Records whether the planned run passed budget checks, triggered a warning, was blocked, or recommended a downgrade before spend.
Policy application
Captures which policies matched, which modes applied, and whether extra evidence or enforcement conditions were required.
Idempotent retries
Use
idempotency_key for safer retries so repeated submissions can be deduplicated and tracked consistently.Receipts, evidence, and verification
A completed run is meant to be auditable. Attestify can return a receipt reference, structured evidence items, verification signals, and settlement details so builders can inspect not only the output but also the route, spend, and governance record.
{
"receipt_url": "/receipts/loop1715000000000abcdef12",
"evidence": {
"version": "2026-05-evidence-v1",
"items": [
{ "kind": "routing", "source": "router" },
{ "kind": "pricing", "source": "pricing-engine" },
{ "kind": "budget", "source": "budget-record" },
{ "kind": "policy", "source": "policy-engine" },
{ "kind": "verification", "source": "heuristic-verifier" },
{ "kind": "settlement", "source": "x402" }
]
},
"verification": {
"verified": true,
"score": 0.82,
"grade": "B"
},
"settlement": {
"success": true,
"network": "eip155:8453"
}
}Endpoint index
Once the model is clear, these are the main public surfaces to implement against.
Execution
POST /api/run
Default x402-paid router endpoint. Accepts task, routing preferences, budget and policy governance inputs, then returns decision, pricing, evidence, verification, memory, receipt, and settlement metadata.
POST /api/loop
Lower-level paid execution primitive for direct loop control and backwards compatibility. Keep public integrations centered on /api/run by default.
Financial control plane
POST /api/keys
Provision a tenant API key. Supply org name, email, and plan. Returns an atst_ prefixed key to set as X-API-Key on every subsequent request. Start here — see /onboarding for the self-serve UI.
GET | POST | PUT | DELETE /api/budgets
List, create, update, or archive budget records that can later be referenced by /api/run to cap or warn on spend.
GET | POST | PUT | DELETE /api/policies
List, create, update, or archive policy records that can later be referenced by /api/run for governance enforcement.
POST /api/subscribe
Purchase subscription plans for discounted or expanded Attestify usage.
GET /api/subscriptions
List active subscriptions for the authenticated tenant.
GET /api/tenant/analytics
Tenant-scoped spend analytics: loop counts, total USDC spent, agent usage breakdown, and budget consumption over time.
GET | POST | DELETE /api/webhooks
Register, list, or remove webhook endpoints to receive real-time events for run completions, budget warnings, and policy violations.
GET | POST /api/sla
Define and inspect SLA policies for agent lanes — latency targets, uptime expectations, and breach escalation rules.
Inspect & audit
GET /api/pricing
Public pricing matrix for current lane base prices, orchestration fee, and hosted paid run prices.
GET /api/receipts
List recent stored receipts with optional filters such as session, agent, status, paid, or verified.
GET /api/receipts/{id}
Fetch a stored run receipt by loop_id or run_id returned from /api/run.
Programmatic habit: provision a key at /onboarding, preview hosted prices with
GET /api/pricing, run work through POST /api/run, and use receipts, budgets, and policies to inspect and govern spend over time.