Skip to main content

Query and Streaming

The query endpoints are the primary way human users send prompts to agents. Both blocking and streaming variants share the same request body. All require a human access token. Rate-limited per-IP.

POST /v1/query​

Blocking query. Waits for the full response before returning.

Request

{
  "prompt": "What is the capital of France?",
  "agent": "researcher",
  "session": "my-session"
}
  • agent — agent name. If omitted, uses the default backend directly.
  • session — session ID for conversation continuity. Defaults to "default".

Response 200

{
  "response": "The capital of France is Paris.",
  "tool_used": "web_search",
  "session": "my-session",
  "agent": "researcher"
}

tool_used is null when no tool was invoked.

Errors

  • 503 — no default backend configured, or orchestrator not available for the tenant

POST /v1/stream​

Server-Sent Events (SSE) streaming. Returns partial response chunks as they arrive from the LLM.

Request — same shape as /v1/query.

Response — Content-Type: text/event-stream, Cache-Control: no-cache

Each event is a JSON payload:

data: {"text":"The capital"}

data: {"text":" of France is Paris."}

data: {"done":true}

On upstream error:

data: {"error":"backend connection reset"}
curl -s -X POST http://localhost:8080/v1/stream \
  -H "Authorization: Bearer $ACCESS" \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Tell me a haiku about Go.","agent":"writer"}' \
  --no-buffer

POST /v1/triggers​

Enqueues an asynchronous agent run from an external source (webhooks, schedulers). Does not wait for the agent to complete.

Requires a human access token. The caller must have access to the target agent (checked against allowed_agents).

Supports traceparent header for distributed trace propagation.

Request

{
  "target_agent": "daily-summarizer",
  "input": "Run the daily summary for project ACME"
}

Response 202

{
  "event_id": "01HXZ...",
  "status": "pending"
}

Errors

  • 403 — user not authorized for the target agent
  • 404 — agent not found
curl -s -X POST http://localhost:8080/v1/triggers \
  -H "Authorization: Bearer $ACCESS" \
  -H 'Content-Type: application/json' \
  -H 'traceparent: 00-abc...' \
  -d '{"target_agent":"daily-summarizer","input":"Run now"}' | jq .