Router API And Inference Flow¶

Last updated: 2026-06-28

The router is the bridge between external clients and decentralized inference sessions. It accepts requests, resolves or selects sessions, writes tasks, watches miner outputs, and returns results or validation verdicts.

Completion routes v1 / v2 / v3

v1 handles direct prompts, while v2/v3 support off-chain and encrypted payload references for larger or private work.

Delegate routes replica fanout

Delegate sends work across configured replica sessions and returns output with policy-controlled aggregation.

Validate routes verdict flow

Validate checks a claim or candidate result through configured validation sessions and returns score/verdict metadata.

Agent/payment routes MCP / A2A / x402

MCP and A2A make the router agent-facing; x402 adds payment-gated access where configured.

Entrypoints¶

flowchart LR
  Customer["Customer app"] --> Hosted["Hosted API<br/>/v1/completions"]
  Portal["Portal"] --> Hosted
  Agent["Agent framework"] --> Direct["Direct router API"]
  Corgent["Corgent"] --> Direct
  PyClaw["PyClaw"] --> Direct

  Hosted --> Gateway["API Gateway<br/>keys / usage / model mapping"]
  Gateway --> RouterPool["Managed router pool"]
  Direct --> RouterPool

  RouterPool --> Completion["Completions"]
  RouterPool --> Delegate["Delegate"]
  RouterPool --> Validate["Validate"]
  RouterPool --> Factcheck["Factcheck"]
  RouterPool --> Protocols["A2A / MCP"]

  Completion --> Network["Cortensor task lifecycle"]
  Delegate --> Network
  Validate --> Network
  Factcheck --> Network

Core Flow¶

sequenceDiagram
  participant App as Application / Product
  participant Router as Router Node
  participant Queue as SessionQueue
  participant Miner as Miner
  participant Validator as Validator / Oracle

  App->>Router: completions / delegate / validate
  Router->>Queue: create or enqueue task
  Queue->>Miner: assign task
  Miner->>Queue: precommit hash
  Miner->>Queue: commit result or URN
  Validator->>Queue: validate and close lifecycle
  Router-->>App: result, consensus output, or verdict

Route Families¶

flowchart TB
  Caller["Application / agent / gateway"] --> Router["Router REST API"]
  Router --> Meta["Health / Info<br/>about, info, status, ping, miners"]
  Router --> Completion["Completions<br/>v1 / v2 / v3"]
  Router --> Delegate["Delegate<br/>v1 / v2 / v3"]
  Router --> Validate["Validate<br/>v1 / v2 / v3"]
  Router --> Factcheck["Factcheck<br/>v1"]
  Router --> AgentProtocols["Agent protocols<br/>A2A / MCP"]
  Router --> Payments["Trial / x402"]
  Router --> Privacy["Privacy / Off-chain"]

Off-Chain Payload Flow¶

flowchart TB
  Request["v2 / v3 request"] --> Router["Router"]
  Router --> Privacy{"Privacy or size policy"}
  Privacy -->|"inline allowed"| Task["Task payload"]
  Privacy -->|"off-chain required"| Store["Object storage"]
  Store --> Ref["URN reference"]
  Ref --> Task
  Task --> Queue["SessionQueue"]
  Queue --> Miner["Miner"]
  Miner --> ResultPrivacy{"Result policy"}
  ResultPrivacy -->|"inline allowed"| Response["Router response"]
  ResultPrivacy -->|"off-chain result"| ResultStore["Result storage"]
  ResultStore --> ResultRef["Result URN"]
  ResultRef --> Response

Family	Notes
Completions	`POST /api/v1/completions`, `POST /api/v2/completions`, and `POST /api/v3/completions`; each accepts optional `/<session_id>`. v2/v3 can use off-chain payloads.
Delegate	`POST /api/v1/delegate`, `POST /api/v2/delegate`, and `POST /api/v3/delegate`. v3 fans out across predefined session pools by `replicas`.
Validate	`POST /api/v1/validate`, `POST /api/v2/validate`, and `POST /api/v3/validate`. v3 aggregates verdicts from predefined validate sessions.
Factcheck	`POST /api/v1/factcheck` and `POST /api/v1/fact-check` with standard/realtime modes where configured.
Trial	Quota-limited routes for evaluation.
x402	Payment-gated routes when middleware is enabled.
A2A	Agent card and discovery routes.
MCP	Streamable HTTP and legacy SSE surfaces where enabled.
Privacy/off-chain	Encrypted payload and signed off-chain result handling.

See Web2 API Reference for the route matrix.

Failure Modes To Document¶

Failure	Public behavior to capture
Missing session	Error when no session ID or configured default exists.
Missing v3 session pool	Delegate/validate v3 returns configuration error.
All replicas fail	v3 returns failed status with per-replica raw payloads.
Router timeout	Gateway and router return request IDs and timeout codes.
Encrypted streaming	Streaming may be disabled when encrypted payloads are used.