Gateway API reference
Generated from docker/server/gateway.py.
Public API (port 9090, TLS)
Clients authenticate with Authorization: Bearer <device token>. oppx adds it; agents talk to oppx’s loopback proxy.
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /health | none | Liveness and model readiness; no token needed. |
| POST | /v1/pair | none | Trades a one-time pairing code for a device token. |
| GET | /v1/whoami | device token | Lets a client confirm its token is still valid (e.g. oppx status). |
| GET | /v1/info | device token | Which model this server runs and how clients should drive it, so the client adapts to any model instead of assuming one. |
| POST | /v1/tokenize | device token | Exact token count with the served model’s own tokenizer (the client calibrates its context budget with it). |
| POST | /v1/unpair | device token | Lets a client revoke its own token when it forgets this server. |
| POST | /v1/search | device token | Web search through the private SearXNG instance: {query, max_results} → {results: [{title, url, snippet}]}. |
| GET | /v1/models | device token | OpenAI-compatible model list (the one served model). |
| POST | /v1/chat/completions | device token | OpenAI-compatible chat completions (streaming supported), with safety limits and optional automatic web search (X-Oppx-Web-Search: auto). |
Admin API (127.0.0.1:9091)
Used by the server app; needs the per-launch x-admin-token.
| Method | Path | Description |
|---|---|---|
| GET | /admin/status | Backend, SGLang and gateway state for the server app (asked every 2 s). |
| GET | /admin/trace | Requests newer than after (and unfinished older ones), with the prefix cache’s pool state. |
| GET | /admin/trace/tree | The tree of shared prompt prefixes among the latest requests. |
| PUT | /admin/trace/content | Keeps (or stops keeping, and drops) the latest message and the reply of each request, in memory. |
| DELETE | /admin/trace | |
| POST | /admin/pairing | Issues a new pairing code (single use, 10 minutes). |
| DELETE | /admin/pairing | Cancels the current pairing code. |
| GET | /admin/devices | Paired devices with their usage counts. |
| GET | /admin/pairing-policy | |
| PUT | /admin/pairing-policy | Changes how long pairings last, for every device (the app also passes it as DEVICE_TTL_DAYS at start). |
| DELETE | /admin/devices/{device_id} | Revokes a device; its token stops working immediately. |