# Use the pool

Requests go through your own node: a running `hyverk-node` (see
[Join](join.md)) serves an OpenAI-compatible API on `127.0.0.1:17080`.
Only running nodes can send requests; there is no public completion
endpoint and no API key to manage. Lending is not required to use it.

## Endpoints

| Method | Path | |
|--------|------|-|
| POST | `/v1/chat/completions` | Chat, streaming with `"stream": true` |
| POST | `/v1/completions` | Plain text completion |
| GET | `/v1/models` | The model the pool serves now |
| GET | `/status` | This node: lending, budget, engine, pool state |

## curl

```bash
curl -s http://127.0.0.1:17080/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{
    "messages": [{"role": "user", "content": "Write a haiku about shared GPUs."}],
    "max_tokens": 200
  }'
```

## OpenAI SDKs

Any client that takes a base URL works. The key is ignored but most SDKs
require one.

```python
from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:17080/v1", api_key="unused")
model = client.models.list().data[0].id
reply = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "Summarize RFC 6455 in five lines."}],
    stream=True,
)
for chunk in reply:
    print(chunk.choices[0].delta.content or "", end="", flush=True)
```

```javascript
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "http://127.0.0.1:17080/v1", apiKey: "unused" });
const r = await client.chat.completions.create({
  model: (await client.models.list()).data[0].id,
  messages: [{ role: "user", content: "Name three uses of a layer split." }],
});
console.log(r.choices[0].message.content);
```

## Reasoning models

Models in the catalog may think before answering. To skip the thinking
pass on Qwen models, add
`"chat_template_kwargs": {"enable_thinking": false}` to the request body.

## Limits

- `max_tokens` is capped at 16384 and set to that when absent. Ask for less
  when you can: a long request holds one of the head's few parallel slots.
- Request bodies up to 8 MB.
- Up to 4 requests in flight per node toward the head; more wait in line on
  your own node.
- The context window is on `/v1/models` (`context_length`).

## When the pool is not serving

`503` with `Retry-After: 30` and the pool state in the body:

```json
{"error": {"message": "the pool is not serving a model right now", "type": "pool_unavailable"},
 "pool": {"state": "forming", "generation": 4, "members": 2, "nodes_online": 3}}
```

`forming` means a model is loading, often for a few minutes after the
machines change. `idle` means not enough memory is being lent to hold any
catalog model.

## What the head machine sees

Your prompt and the answer are visible to the head machine (it runs the
engine) and pass through the hub. Workers see intermediate activations, not
text. Do not send secrets. See [Security](security.md).
