StationLM Agent API

Query the StationLM knowledge graph for human speech from your own project — or from ChatGPT or Claude. Same agent, same tools, same conversation memory as the web app, over an API-key-authenticated HTTP endpoint. Mint a key in Settings → API Keys.

Authentication

Pass your key as a Bearer token. The key looks like sk_live_<id>_<secret> and is shown only once at creation — store it securely; it can't be retrieved later. The key supplies your identity; all data access is scoped to your account.

Authorization: Bearer sk_live_<id>_<secret>

Query the agent

POST /api/v1/agent

Request body:

{
  "question": "Which CEOs guested on diagnostics podcasts this year?",  // required
  "conversation_id": "uuid",   // optional — continue a prior conversation
  "scope_type": "all" | "category" | "show",  // optional
  "scope_id": "uuid",          // optional — required when scope_type is category/show
  "stream": true               // optional — default true (SSE); false returns JSON
}

JSON mode (stream: false)

curl -X POST https://stationlm.com/api/v1/agent \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"question":"Who sponsors the top fintech podcasts?","stream":false}'

Response:

{
  "conversation_id": "uuid",
  "answer": "Markdown answer with inline citations…",
  "tool_calls": [ { "tool": "get_sponsors", "input": {…}, "result": {…} } ],
  "usage": {
    "input_tokens": 1234,
    "output_tokens": 567,
    "cache_read_tokens": 5901,
    "cache_creation_tokens": 0,
    "tool_calls": 2
  }
}

Streaming mode (stream: true, default)

Returns text/event-stream. Each line is data: <json>. Event types:

• conversation — { id, title? }, emitted first (and again with the title on a new conversation)
• status — a human-readable progress string
• content — the final markdown answer (emitted once)
• error — an error string (still followed by done)
• done — terminal event; the stream then closes

data: {"type":"conversation","data":{"id":"…"}}

data: {"type":"status","data":"Analyzing your question..."}

data: {"type":"content","data":"On The Diagnostics Show (Medicine, …) …"}

data: {"type":"done"}

Rate limits & cost guardrails

• Per-key daily requests — default 100/day. Exceeding it returns 429.
• Global cost cap — a platform-wide daily safety net returns 503 when reached; retry the next day.
• Per-key spend cap — an interim $10 lifetime cap per key guards against a leaked key. Billable operations are blocked once a key reaches it (with a "contact the team" message). Reading the corpus never spends.

Status codes

• 200 — success (JSON, or the SSE stream)
• 400 — missing/invalid question or body
• 401 — missing, malformed, or revoked key
• 429 — per-key daily request limit reached
• 503 — global daily cost cap reached

Manage conversations

Resume a conversation by passing its conversation_id on the main endpoint. List and delete with:

GET    /api/v1/agent/conversations          → { conversations: [ { id, title, … } ] }
DELETE /api/v1/agent/conversations/{id}     → { success: true }

Both require the same Bearer key and are scoped to your account.

Versioning

The API is versioned in the path (/api/v1/agent). There is no header negotiation in v1. Breaking changes will ship under a new version path.