Agent API

The agent API is Vexa’s control plane. It turns triggers into dispatches and streams their output; it does no execution itself — it validates and hands off to the runtime. Endpoints are fronted by the gateway, which carries authentication and per-route scopes; the service itself is internal.

Identity is server-derived. Public clients reach these routes through the gateway under the canonical prefix /agent/*. The gateway resolves your X-API-Key → user and injects X-User-Id; agent-api derives the workspace/chat/quota subject from that header (P20). A subject in a request body or query string is ignored — never trust the client for identity. The $AGENT_API/api/... paths below address the internal service directly (which requires X-User-Id); through the gateway the same routes are $API_BASE/agent/... with X-API-Key.

Health

GET /health

curl "$AGENT_API/health"   # → {"status":"ok","service":"agent-api","checks":{"dispatcher":true}}

Models

GET /api/models → the resolved model names for this subject:

{ "chat_model": "...", "agent_model": "...", "streaming_model": "...", "meeting_model": "..." }

Dispatch a unit

POST /invocations — the sink every trigger funnels through. Body is a conformant unit.v1 Invocation (the same envelope units.make_dispatch builds); it is validated and dispatched to the runtime. 400 if the envelope is non-conformant.

POST /invocations → 202

curl -X POST "$AGENT_API/invocations" -H "Content-Type: application/json" -d '{
  "identity":{"subject":"u_jane","launcher":"schedule:u_jane"},
  "runner":"claude-code",
  "workspaces":[{"id":"u_jane","mode":"rw"}],
  "trigger":"scheduled",
  "start":{"entrypoint":{"inline":"Summarize overnight activity."}}
}'   # → {"workload_id":"agent-..."}

The shape is: identity.subject + identity.launcher, runner, a workspaces list (mode is rw for trusted triggers — message/scheduled — else ro), the trigger, and a start that is either {"entrypoint":{"inline":"..."}}, {"entrypoint":{"path":"..."}}, or {"session":{"ref":"..."}}. There is no top-level subject, workspace_repo, or plan field.

Chat (streamed)

POST /api/chat — body { prompt, session?, active? } (subject is server-derived, not sent). Returns Server-Sent Events; each data: line is one frame:

frame	fields
`message-delta`	`text`
`tool-call`	`tool`, `args`, `callId`
`tool-result`	`callId`, `ok`, `summary`
`commit`	`sha`
`rejected`	`violations`
`done`	`reply`, `sessionId`, `ok` (+ `detail` when a failure’s raw provider text was rewritten)
`error`	`message` — the turn was refused before dispatch (e.g. no model credential configured); actionable, names what to set

POST /api/chat (SSE)

curl -N -X POST "$AGENT_API/api/chat" -H "Content-Type: application/json" \
  -H "X-User-Id: u_jane" \
  -d '{"prompt":"Record that Acme renewed."}'

POST /api/chat/reset { session? } → { "ok": true } · GET /api/sessions → { "sessions": [...] } · GET /api/sessions/{session}/history → { "turns": [...] } (tolerant — a missing transcript returns { "turns": [] }).

Routines

POST /api/routines → 201

curl -X POST "$AGENT_API/api/routines" -H "Content-Type: application/json" \
  -H "X-User-Id: u_jane" -d '{
  "name":"Morning brief","cron":"0 8 * * 1-5",
  "prompt":"Brief me from overnight activity.","run_now":true
}'   # → {"routine":{...},"job_id":"job_...","ran_now":true}

GET /api/routines → { "routines": [...] } · PATCH /api/routines/{name}/enabled { enabled } → { "ok": true, "name", "enabled", "reconcile" } · DELETE /api/routines/{routine_id} → { "ok": true, "routine_id": "..." }.

Events

POST /events — body is an event.v1 Event (an integration firing). It maps to a unit.v1 Invocation and dispatches. 400 if non-conformant; 422 if the event carries no plan.

POST /events → 202

curl -X POST "$AGENT_API/events" -H "Content-Type: application/json" -d '{
  "name":"email.received","subject":"u_jane",
  "source":{"uri":"mailbox://u_jane/INBOX/AB12CD"},
  "plan":{"prompt":"Triage this email into tasks."}
}'   # → {"workload_id":"agent-...","trigger":"event"}

Live meeting copilot

A live-meeting copilot is itself driven through make_dispatch; the id invariant is meeting_id == session_uid == native_id.

POST /api/meeting/start { native_id, platform, title? } → 202, returns the live-meeting record.
POST /api/meeting/process { native_id, platform, on } → toggle opt-in processing. on:true resumes from the per-meeting cursor ({ ..., "processing":true, "resumed_from":"<id>" }); on:false clears the flag and freezes the cursor ({ ..., "processing":false }).
GET /api/meeting/relay-health → typed transcript-relay health (a stale bot key surfaces as native_resolve:{ok:false,kind:"unauthorized"} rather than silent dead air).
GET /api/meeting/stream?meeting_id=&session_uid= (SSE) → the merged transcript + copilot-output feed. Resumable: every event carries an SSE id:; on reconnect echo it as Last-Event-ID to resume gaplessly. Event types: transcript, card, message-delta, tool-call, ping, meeting-end.

Workspace

GET /api/workspace/tree?hidden= → { "files": ["kg/entities/..."] } · GET /api/workspace/file?path= → { "path": "...", "content": "..." } (404 if absent) · GET /api/workspace/git → { branch, changes, commits } · POST /api/workspace/upload (multipart files, ≤25 MB each) → { "files": [{ name, path }] } · POST /api/workspace/init → 201 { workspace, seeded, already_initialized } (idempotent) · GET /api/workspace/attached → { active, parked } · POST /api/workspace/swap { repo?, ref?, token? } → attach an external git repo as the active workspace (parks the current one; omit repo to swap back to the seed). (All workspace routes derive subject from X-User-Id — no subject query parameter.)

Start here

How-to: Meetings

How-to: Agents

How-to: Meetings + agents

Core

Concepts

Architecture

API reference

Deployment & operations

Roadmap

Governance

Health

Models

Dispatch a unit

Chat (streamed)

Routines

Events

Live meeting copilot

Workspace

​Health

​Models

​Dispatch a unit

​Chat (streamed)

​Routines

​Events

​Live meeting copilot

​Workspace

Health

Models

Dispatch a unit

Chat (streamed)

Routines

Events

Live meeting copilot

Workspace