Kurier Docs for LLM Agents
Last updated: 2026-04-22

Retrieval mode:
- Fetch all resources via plain HTTP GET (no browser rendering or scraping required).
- Treat this file as the entrypoint, then fetch machine endpoints directly.
- Default environment policy: use testnet unless user explicitly requests mainnet.
- docsBase (mainnet): https://kurier.xyz/docs
- docsBase (testnet): https://testnet.kurier.xyz/docs

Fetch all pages algorithm (no browsing):
1) GET {docsBase}/agent/docs-index.json
2) Read pages[]. For each page item:
   - version -> mainnet or testnet
   - path -> doc path (empty path means index)
3) Map path to page filename:
   - if path is empty, page = index
   - else page = path
4) Fetch either:
   - JSON: {docsBase}/agent/pages/{version}/{page}.json
   - MD: {docsBase}/agent/pages/{version}/{page}.md

Concrete examples:
- Mainnet index JSON: https://kurier.xyz/docs/agent/pages/mainnet/index.json
- Mainnet supported proofs MD: https://kurier.xyz/docs/agent/pages/mainnet/supported_proof_types.md
- Testnet index JSON: https://testnet.kurier.xyz/docs/agent/pages/testnet/index.json
- Testnet tutorial base sepolia MD: https://testnet.kurier.xyz/docs/agent/pages/testnet/tutorial_base_sepolia.md

Fetch non-page assets (proof examples/scripts):
1) GET {docsBase}/agent/assets-index.json
2) Read assets[]. Use urls.mainnet or urls.testnet for direct GET fetches
3) For scripts, review execution.guidance before running
4) Never auto-execute scripts without explicit user approval

Canonical docs:
- Mainnet docs: https://kurier.xyz/docs
- Testnet docs: https://testnet.kurier.xyz/docs
- Mainnet supported proof types: https://kurier.xyz/docs/supported_proof_types
- Testnet supported proof types: https://testnet.kurier.xyz/docs/supported_proof_types

Canonical API and schema:
- Mainnet API base: https://api.kurier.xyz/api/v1
- Testnet API base: https://api-testnet.kurier.xyz/api/v1
- Mainnet Swagger: https://api.kurier.xyz/docs
- Testnet Swagger: https://api-testnet.kurier.xyz/docs

Authentication pattern:
- API key is path-based in these docs: /{endpoint}/{apiKey}/...
- WebSocket auth uses query parameter: ?apiKey=YOUR_API_KEY
- Do not assume Authorization headers unless endpoint schema explicitly states it.

Operator prerequisites:
- Operator must register and obtain API key before proof submission.
- Mainnet portal: https://kurier.xyz
- Testnet portal: https://testnet.kurier.xyz

Critical workflow (recommended):
1) Register VK per circuit:
   - Mainnet: POST https://api.kurier.xyz/api/v1/register-vk/{apiKey}
   - Testnet: POST https://api-testnet.kurier.xyz/api/v1/register-vk/{apiKey}
2) Store vkHash and submit proofs with vkRegistered=true
3) Track via job-status endpoint or websocket

Key endpoint templates:
- Submit proof (mainnet): POST https://api.kurier.xyz/api/v1/submit-proof/{apiKey}
- Submit proof (testnet): POST https://api-testnet.kurier.xyz/api/v1/submit-proof/{apiKey}
- Register VK (mainnet): POST https://api.kurier.xyz/api/v1/register-vk/{apiKey}
- Register VK (testnet): POST https://api-testnet.kurier.xyz/api/v1/register-vk/{apiKey}
- Job status (mainnet): GET https://api.kurier.xyz/api/v1/job-status/{apiKey}/{jobId}
- Job status (testnet): GET https://api-testnet.kurier.xyz/api/v1/job-status/{apiKey}/{jobId}
- WebSocket (mainnet): wss://api.kurier.xyz/api/v1/ws?apiKey=YOUR_API_KEY
- WebSocket (testnet): wss://api-testnet.kurier.xyz/api/v1/ws?apiKey=YOUR_API_KEY
- WebSocket docs (mainnet): https://kurier.xyz/docs/websocket
- WebSocket docs (testnet): https://testnet.kurier.xyz/docs/websocket

vkRegistered semantics:
- false: proofData.vk = full verification key
- true: proofData.vk = registered vkHash
- Circuit changes create new VKs: register each new VK

Status handling guidance:
- Final states include Finalized, Aggregated, and Failed.
- Do not treat Valid as final settlement.

Machine endpoints:
- Mainnet llms-full: https://kurier.xyz/docs/llms-full.txt
- Testnet llms-full: https://testnet.kurier.xyz/docs/llms-full.txt
- Mainnet docs index: https://kurier.xyz/docs/agent/docs-index.json
- Testnet docs index: https://testnet.kurier.xyz/docs/agent/docs-index.json
- Mainnet assets index: https://kurier.xyz/docs/agent/assets-index.json
- Testnet assets index: https://testnet.kurier.xyz/docs/agent/assets-index.json
- Page JSON template: {docsBase}/agent/pages/{version}/{page}.json
- Page MD template: {docsBase}/agent/pages/{version}/{page}.md
- Changelog NDJSON: {docsBase}/agent/docs-changelog.ndjson

Top task docs:
- VK registration + why: https://kurier.xyz/docs/FAQ
- Supported proof types: https://kurier.xyz/docs/supported_proof_types
- Job statuses: https://kurier.xyz/docs/job_statuses
- WebSocket API: https://kurier.xyz/docs/websocket