Skip to content
2 min read · 386 words

API Reference

Base URL http://localhost:8001. JSON everywhere (multipart for upload). No authentication. Interactive Swagger UI at /docs.

Conventions

  • Path base: both routers mount under /agents — document routes nest as /agents/{agent_id}/documents/....
  • Validation: request bodies are Pydantic-validated (Schemas); violations return 422 with FastAPI's standard detail array.
  • Existence guard: almost every route 404s first if {agent_id} doesn't resolve.
  • Tool gating: tool-bearing routes 403 when the agent lacks the required tool (Tools).
  • Ordering: list endpoints return newest-first (id desc), except workflow steps and chunks (oldest-first) and messages (newest-first with limit/offset pagination).
  • Trailing slashes matter on the collection routes: POST /agents/ and GET /agents/ (with slash).

Endpoint directory

System

MethodPathPurpose
GET/liveness message
GET/healthhealth probe

Agents & Chat

MethodPathPurpose
POST/agents/create agent
GET/agents/list agents
GET/agents/{id}get agent
POST/agents/{id}/chatchat exchange
GET/agents/{id}/runschat run history
GET/agents/{id}/messagespaginated messages
GET/agents/{id}/tool-callstool-call log
GET/agents/{id}/dashboardaggregated metrics
GET/agents/{id}/stats⚠️ broken — do not use (details)

Tasks & Email

MethodPathPurpose
POST/agents/{id}/email/analyzeanalyze email, optionally create tasks
GET/agents/{id}/taskslist tasks
PUT/agents/tasks/{task_id}/statusupdate task status

Workflows

MethodPathPurpose
POST/agents/{id}/workflows/emailrun the multi-agent email workflow
GET/agents/{id}/workflow-runslist workflow runs
GET/agents/workflow-runs/{run_id}/stepsone run's step trace

Documents & RAG

MethodPathPurpose
POST/agents/{id}/documents/uploadingest a .txt document
GET/agents/{id}/documentslist documents
GET/agents/{id}/chunkslist stored chunks
POST/agents/{id}/documents/searchraw vector search
POST/agents/{id}/documents/askcorrective-RAG answer

Errors

Status-code semantics, error body shapes, and how clients should handle each.

Quick sanity sequence

bash
curl http://localhost:8001/health
curl -X POST http://localhost:8001/agents/ -H "Content-Type: application/json" \
  -d '{"name":"Test","type":"Email Ops","system_prompt":"You are helpful.","enabled_tools":"email_analyzer"}'
curl http://localhost:8001/agents/
PreviousPrompt CatalogNextAgents & Chat