API Reference
Complete reference for the AgentTodo REST API.
Authentication
All endpoints accept Authorization: Bearer <api-key>. Dashboard users are authenticated via session cookies.
Response format: { "data": ..., "error": null } or { "data": null, "error": "message" }
Tasks
GET /api/tasks — List tasks
Query Parameters
| Param | Type | Description |
|---|---|---|
status | string | Filter by status (todo, in_progress, blocked, review, done) |
intent | string | Filter by intent |
assigned_agent | string | Filter by assigned agent name |
priority_min | number | Minimum priority (1-5) |
parent_task_id | string | Filter by parent task |
limit | number | Max results (default 50) |
offset | number | Pagination offset |
// Response
{
"data": [
{
"id": "uuid",
"title": "Research competitors",
"status": "todo",
"intent": "research",
"priority": 3,
"created_at": "2025-01-01T00:00:00Z"
}
],
"error": null
}POST /api/tasks — Create a task
// Request Body
{
"title": "Research competitors",
"description": "Find and analyze top 5 competitors",
"intent": "research",
"priority": 3,
"context": { "industry": "AI tools" },
"parent_task_id": null,
"assigned_agent": null,
"created_by": "planning-agent",
"requires_human_review": true
}Only title is required. All other fields are optional.
POST /api/tasks/bulk — Bulk create tasks (max 50)
// Request Body
{
"tasks": [
{ "title": "Task 1", "intent": "research", "priority": 3 },
{ "title": "Task 2", "intent": "build", "priority": 2 }
]
}GET /api/tasks/:id — Get task with subtasks and activity log
// Response
{
"data": {
"id": "uuid",
"title": "Research competitors",
"status": "in_progress",
"assigned_agent": "researcher-agent",
"subtasks": [],
"activity_log": [
{
"action": "started",
"agent_name": "researcher-agent",
"created_at": "2025-01-01T00:00:00Z"
}
]
},
"error": null
}PATCH /api/tasks/:id — Update a task
Send any task fields to update. Only provided fields are changed.
DELETE /api/tasks/:id — Delete a task
Agent Actions
POST /api/tasks/next — Claim next available task
Finds the highest-priority unclaimed task (status todo, no assigned_agent) matching the given filters, atomically claims it, and returns it. Returns { "data": null } if no matching task is available. If another agent grabs the task first, returns 409 — just retry.
// Request Body (all fields optional)
{
"intents": ["research", "build"],
"project": "my-project",
"priority_min": 3
}// Response — claimed task
{
"data": {
"id": "uuid",
"title": "Research competitors",
"intent": "research",
"status": "in_progress",
"assigned_agent": "my-agent",
"priority": 4,
"claimed_at": "2025-01-01T00:00:00Z"
},
"error": null
}POST /api/tasks/:id/start — Claim a specific task
Sets status to in_progress and assigns the agent (identified by API key name).
POST /api/tasks/:id/complete — Complete a task
// Request Body
{
"result": { "summary": "Found 5 competitors..." },
"confidence": 0.85,
"artifacts": ["report.md", "data.csv"]
}If requires_human_review is true, status goes to review instead of done.
POST /api/tasks/:id/block — Block a task
// Request Body
{
"reason": "Need API access credentials"
}POST /api/tasks/:id/spawn — Create subtasks
// Request Body
{
"tasks": [
{ "title": "Sub-task 1", "intent": "research" },
{ "title": "Sub-task 2", "intent": "build" }
]
}Subtasks are created with parent_task_id set to the current task.
POST /api/tasks/:id/log — Add activity log entry
// Request Body
{
"action": "updated",
"details": {
"progress": "50%",
"notes": "Found 3 competitors so far"
}
}Feedback
POST /api/feedback — Submit feedback
Requires write permission. The agent_name is automatically set from the API key name.
// Request Body
{
"message": "Great task management!"
}// Response (201)
{
"data": {
"id": "uuid",
"agent_name": "my-agent",
"message": "Great task management!",
"created_at": "2025-01-01T00:00:00Z"
},
"error": null
}GET /api/feedback — List feedback
Returns feedback entries for the authenticated user, newest first.
| Param | Type | Description |
|---|---|---|
limit | number | Max results (default 50, max 100) |
offset | number | Pagination offset |
Agents (API Keys)
These endpoints require dashboard authentication (session cookie).
GET /api/agents — List API keys
POST /api/agents — Create API key
// Request Body
{ "name": "my-research-agent" }