VORQ DocsAPI conventions
Encoding, numbers, headers, body limits, paging and freshness rules shared by every route.
Base URL
Every path in this reference is relative to the coordinator's base URL, https://api.vorq.co for the VORQ coordinator. The default port for a self-hosted node is 8402.
Bodies and encoding
- Request and response bodies are JSON unless a route says otherwise. Send
content-type: application/json. - Byte values are
0x-prefixed hex: addresses (20 bytes), hashes and ids (32 bytes), signatures (65 bytes). - Payload bytes in JSON (
container,result) are canonical padded base64. - A query parameter may appear at most once; an empty value counts as absent.
Numbers
- Responses. Integers that can exceed 32 bits (ids from the index, rates, amounts, block numbers, unit counts) are decimal strings. Small enumerations (
state,ended_because,fee_bps,decimals,chain_id) and Unix timestamps on auth, file and batch objects are JSON numbers. Each route's example shows which. - Requests. Integer fields accept a JSON number (safe integers only) or a decimal string. Use strings for anything above 2^53.
Headers
| Header | Direction | Meaning |
|---|---|---|
authorization: Bearer vorq_sess_… | request | Session token, on routes that need one. See Auth API. |
x-request-id | response | An id for this request, on every response. Quote it when reporting a problem. |
x-vorq-retryable | response | true or false on every error response: whether the identical request may succeed later. See Errors. |
x-vorq-page-truncated | response | On paged routes. See Paging. |
x-vorq-next-offset | response | On truncated pages. See Paging. |
Body limits
| Route | Limit |
|---|---|
POST /v1/jobs, POST /evm/ops | 20 MiB |
PUT /evm/asks | 32 KiB |
POST /v1/jobs/{id}/cancel | 8 KiB |
POST /handover | 4 KiB |
POST /release | 2 KiB |
POST /v1/files | MAX_BLOB_BYTES for the file part (200 MiB by default) |
| Every other route | 1 MiB |
A JSON body over its limit answers 413 with code: "body_too_large". Payloads larger than 15 679 488 bytes decoded cannot be sent inline; upload them with POST /v1/files.
Freshness
Index-backed routes carry as_of_block, the last block the index had processed when the answer was read, and answer 503 not_ready while the index trails the chain by more than READY_LAG_BLOCKS. Chain-backed and write routes carry no as_of_block and are not held back by index lag. Each route below says which it is. See Indexing and readiness.
Paging
Routes marked Paged take:
| Query | Default | Range |
|---|---|---|
limit | 100 | 1–1000 |
offset | 0 | 0–1000000 |
and always set x-vorq-page-truncated. A page is cut short when its body would pass 4 MiB; then the header is true and x-vorq-next-offset gives the offset to request next.
Keep paging while the page is full (returned == limit) or x-vorq-page-truncated is true. See Page through listings.
GET /v1/batches pages by cursor instead; see GET /v1/batches.
CORS
A coordinator sends CORS headers only for the origins its operator lists in CORS_ORIGINS. Browsers may read x-request-id, x-vorq-retryable, x-vorq-page-truncated and x-vorq-next-offset. Credentialed requests are not supported; send the session as a bearer header.