reference
REST API
HTTP endpoints for the Ninetrix local API server.
The local API server runs at http://localhost:8000. All endpoints require Authorization: Bearer <token> using your machine secret from ~/.agentfile/.api-secret.
Threads
| Method | Path | Description |
|---|---|---|
GET | /threads | List all threads — latest checkpoint per thread |
GET | /threads/{thread_id} | Full thread detail with extracted logs |
GET | /threads/{thread_id}/checkpoints | All checkpoints ordered by step |
Approvals
| Method | Path | Description |
|---|---|---|
GET | /approvals | List pending HITL approvals |
POST | /approvals/{trace_id}/{step}/approve | Approve a pending tool call |
POST | /approvals/{trace_id}/{step}/reject | Reject a pending tool call |
Runner events
| Method | Path | Description |
|---|---|---|
POST | /internal/v1/runners/events | Agent telemetry — batch of runner events |
GET | /v1/runners/threads/{thread_id}/latest | Fetch the latest checkpoint for a thread — used by agents on restart to resume from the last saved state |
Channels
Channels connect inbound messaging platforms (Telegram, WhatsApp) to running agents. All /v1/channels/* endpoints require Authorization: Bearer <token> except the public webhook receiver.
| Method | Path | Description |
|---|---|---|
GET | /v1/channels | List all configured channels |
POST | /v1/channels | Create a channel (channel_type, name, config, session_mode, routing_mode) |
GET | /v1/channels/{id} | Get channel details including bound agents |
PATCH | /v1/channels/{id} | Update name, session_mode, routing_mode, or enabled |
DELETE | /v1/channels/{id} | Remove a channel |
POST | /v1/channels/{id}/agents | Bind an agent to a channel (agent_name, is_default, command) |
DELETE | /v1/channels/{id}/agents/{name} | Unbind an agent from a channel |
POST | /v1/channels/{id}/setup-webhook | Register the webhook URL with the messaging platform. Body: {"base_url": "https://your-public-url"}. |
POST | /v1/channels/{id}/verify | Verify channel ownership with the 6-digit code. Body: {"code": "123456"}. |
POST | /v1/channels/webhook/telegram | Public — Telegram Bot API webhook receiver. No auth required. Dispatches inbound messages to bound agents. |
Health
Bash
curl http://localhost:8000/health
# {"status": "ok", "version": "..."}