Documentation / API reference

Inference

The OpenAI-compatible surface: send a chat request, get an answer from whichever node in the network can serve it best.

Create a chat completion

POST/v1/chat/completionsBearerTry it →

OpenAI-compatible. The gateway picks a node by load and price, streams the answer back, and attaches provenance headers.

Body

Field	Type	Description
`model`	string	Model id or alias, e.g. `llama1b`
`messages`	array	Standard `{role, content}` turns
`stream`	boolean	SSE streaming when `true`
`local`	boolean	PyrusLLM extension. Keep the request on this machine; never route to a peer or an external API
`node`	string	PyrusLLM extension. Pin one specific machine by id. No fallback if it is busy

Response headers

Header	Meaning
`X-Pyrus-Operator`	Who answered (URI-encoded)
`X-Pyrus-Kind`	`real` · `peer` · `mock` · `upstream`
`X-Pyrus-Scope`	`local` or `external` — whether the prompt left the network
`X-Pyrus-Model`	The model that actually served it
`X-Pyrus-Cost-Estimate-Micros`	The ceiling the spend was authorised against, in micro-dollars. Not the final cost: with SSE the headers go out before the first token.

X-Pyrus-Scope is the field that matters for privacy. kind: upstream does not by itself mean the prompt left your machine — a llama-server on localhost is also an upstream. scope: external is the one that says a third party saw it.

Example

curl http://localhost:8787/v1/chat/completions \
  -H "Authorization: Bearer $PYRUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "llama1b",
        "messages": [{"role":"user","content":"hello"}],
        "stream": true,
        "local": false
      }'

When streaming, a final SSE event may carry paymentResponse and attestation instead of a completion chunk — it has no choices. See the x402 flow.

List models

GET/v1/modelsNo keyTry it →

OpenAI-compatible catalog of every model the network announces.

{
  "object": "list",
  "data": [{ "id": "llama1b", "object": "model", "owned_by": "pyrusllm" }]
}

Deliberately sanitised: it names the model, never the operator or the price. Those live behind /v1/nodes, which needs a key.