Orchestrator API reference

Base URL: your ngrok or local URL (e.g. https://abc123.ngrok-free.app)

All authenticated endpoints require a Bearer <token> header. Obtain a token via POST /api/auth/login.

Authentication

POST /api/auth/login

{
  "username": "alice",
  "password": "secret"
}

Response:

{
  "access_token": "eyJ...",
  "token_type": "bearer"
}

Status

GET /api/health

Returns { "status": "ok" } when the Orchestrator is running.

GET /api/nodes

Returns all known Aligner nodes with their current status.

[
  {
    "name": "laptop",
    "tailscale_ip": "100.x.x.x",
    "port": 8000,
    "role": "personal",
    "status": "online",
    "sources": ["docs", "code"],
    "compute_score": 0.82
  }
]

Streaming query

WebSocket /ws/stream?token=<JWT>

Connect with a valid JWT token. Send a JSON message to start a query:

{
  "prompt": "What is the authentication flow?",
  "node_filter": ["laptop", "desktop"]
}

Set node_filter to null to query all online nodes.

Incoming messages:

| Type | Fields | Description | |---|---|---| | token | content: string | Streaming LLM token | | done | sources, nodes_queried, escalation_triggered | Response complete | | node_status | node: string, status: NodeStatus | Node status change | | error | message: string | Error (including TOKEN_EXPIRED) |

Transcription

POST /api/transcribe

Accepts multipart/form-data with an audio field (WebM blob). Returns:

{
  "text": "What files are in the aligner?"
}