> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinaivu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway API

> api.pinaivu.com — the OpenAI-compatible developer surface, stateless, per-key auth

`api.pinaivu.com` is the developer-facing surface: each customer holds
their own API key, and the gateway is intentionally **stateless** — no
memory layer, no enclave, just a thin proxy in front of the coordinator.
For the end-user chat product with built-in memory, see
[chat-relayer API](/api-reference/chat-relayer).

```
api.pinaivu.com → gateway (stateless) → coordinator → node (libp2p)
```

Neither this gateway nor its caller ever talks to a node directly — the
coordinator dispatches the job over its existing libp2p connection to the
winning node and returns the final answer in one HTTP round trip.

## Authentication

```
Authorization: Bearer sk-pnv-...
```

Required on every call to `/v1/chat/completions`. Issued per developer via
the gateway's key-management endpoints.

## `POST /v1/chat/completions`

**Request:**

```json theme={null}
{
  "model": "gemma4-e4b-128k:latest",
  "messages": [{ "role": "user", "content": "..." }],
  "client_pubkey_hex": "<64 hex chars — caller's Ed25519 pubkey>",
  "session_id": "<uuid, optional — omit to start a new session>",
  "session_key": "<base64, optional — omit to let the coordinator mint one>",
  "max_price_nanox": 10000
}
```

**Response:**

```json theme={null}
{
  "request_id": "uuid",
  "session_id": "uuid",
  "content": "the model's reply",
  "session_key": "base64 — persist and resend for the next turn of this session",
  "input_tokens": 53,
  "output_tokens": 3,
  "latency_ms": 359
}
```

That's the entire round trip — no `node_url`, no second call. The
coordinator ran the auction, dispatched the job to the winning node over
libp2p, and waited for the reply before responding.

<Note>
  This single-round-trip shape differs from earlier internal docs that
  described a 307-redirect / `node_url` flow — the gateway and chat-relayer
  both now do the node round trip server-side, so callers never see a
  node's address or a dispatch token.
</Note>

### Encrypted mode (optional)

For prompt privacy from the operator, send `client_x25519_pubkey_hex` +
`messages_encrypted` + `messages_nonce` instead of plaintext `messages`,
using an ECDH scheme. Fetch the coordinator's X25519 key from
`GET /enclave_health` first. The gateway passes these fields through
untouched.

## Other routes (no auth required)

| Route                  | Purpose                              |
| ---------------------- | ------------------------------------ |
| `GET /health`          | Liveness                             |
| `GET /enclave_health`  | Coordinator pubkey + uptime, proxied |
| `GET /get_attestation` | Raw NSM attestation document         |
| `GET /v1/models`       | Available models                     |
| `GET /v1/nodes`        | Current peer registry                |

## What a gateway client must persist

|             | Value                       |
| ----------- | --------------------------- |
| Identity    | own API key (`sk-pnv-...`)  |
| Per-session | `session_id`, `session_key` |

A gateway client never persists or sees a node's address, a dispatch
token, or anything node-specific — that's fully internal to the
coordinator.

<Card title="On-chain verification" icon="link" href="/architecture/onchain">
  How the response you get back is independently verifiable on Sui, even
  though you never see the raw receipt directly
</Card>