Agents API

Authentication

Viewer role or above for reads, Editor or above for create and update, Admin or above for delete. See API overview for auth details.

Note: this endpoint group is specialists only. Chatbots live under /api/bots/* and have a separate API surface.

Agents

GET /api/agents

List all agents registered in the instance.

Response: an array of agent definition objects. Each object includes id, name, display name, description, personality (the system prompt), tool grants, model, manager id, keywords, and timestamps.

GET /api/agents/{id}

Get a single agent by id.

Response: the agent definition object, or 404 Not Found.

POST /api/agents

Create a new specialist agent.

Request body: a complete agent definition. Required fields: id, name, description, personality. Optional: displayName, tools, modelId, managerId, keywords, maxConcurrentIssues, metadata.

Response: 201 Created with the new agent object and a Location header at /api/agents/{id}.

Example:

curl -X POST https://your-exolvra.example/api/agents \
  -H "Authorization: Bearer exou_..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "research-analyst",
    "name": "research-analyst",
    "displayName": "Research Analyst",
    "description": "Senior competitive research analyst specializing in SaaS markets.",
    "personality": "You are a senior research analyst. You cite sources. You resist speculation. You write short paragraphs that lead with conclusions...",
    "tools": ["web_search", "web_fetch", "data_store", "memory", "think"],
    "modelId": "claude-sonnet-4-6",
    "keywords": ["research", "competitive", "analysis", "market"]
  }'

PUT /api/agents/{id}

Update an existing agent. Request body is a complete replacement — fields not included are cleared. For partial updates, fetch the current agent with GET, modify the fields you want to change, and PUT the full object back.

Response: the updated agent object.

DELETE /api/agents/{id}

Delete an agent. This is allowed only when the agent has no Open or InProgress issues. If it does, either reassign them first or accept that the reassignment happens automatically.

Response: 204 No Content on success.

Agent adapters status

GET /api/agents/adapters/status

Get the status of configured CLI adapters (Claude Code, Codex, Gemini CLI) across all agents that have them configured.

Response: a summary per adapter type with availability, runtime version, and any detected issues.

Useful for monitoring CLI adapter health in a deployment that uses them heavily. See CLI adapters for the broader context.

Agent work state

Every agent has a work state — a snapshot of what it’s currently doing, its current phase, and its checkpoint history. These endpoints expose that state for observability and debugging.

GET /api/agents/{agentId}/work-state

Get the current work state of an agent.

Response: the latest work state snapshot with fields like current issue, current phase, last turn timestamp, and a short status summary.

GET /api/agents/{agentId}/work-state/history

Get the history of work state snapshots for an agent — one per turn of every issue it has executed.

Query parameters:

Response: an array of work state snapshots, newest first. Each includes the snapshot time, the issue being worked on, the phase at that moment, and the summary of what the agent did in that turn.

Use this when an agent is stuck and you want to see the full history of what it tried.

Example — create, verify, and delete

# Create a new specialist
curl -X POST https://your-exolvra.example/api/agents \
  -H "Authorization: Bearer exou_..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "test-agent",
    "name": "test-agent",
    "description": "Temporary test agent.",
    "personality": "You are a test agent."
  }'

# Verify it was created
curl https://your-exolvra.example/api/agents/test-agent \
  -H "Authorization: Bearer exou_..."

# Delete it when done
curl -X DELETE https://your-exolvra.example/api/agents/test-agent \
  -H "Authorization: Bearer exou_..."

Common pitfalls

Using PUT for a partial update. PUT replaces the whole agent. If you only send {"modelId": "claude-haiku-4-5"}, every other field gets cleared. Always read first, modify, write the whole object back.

Deleting an agent with active issues. Delete is blocked if the agent has Open or InProgress issues. Reassign them or wait for them to complete before deleting.

Confusing agent ids with display names. The id is the canonical handle used everywhere in the API. The displayName is purely for UI. Always use the id in API calls.

Where to go next

• Agents — the dashboard counterpart
• Agents & chatbots — the conceptual model
• Your first agent — the creation walkthrough