Tasks API

Tasks are the core resource in AgentTasks. This reference covers all task endpoints.

List Tasks

GET /api/teams/:teamId/tasks

Returns all tasks in the team. Supports filtering by status and project.

Query Parameters

Parameter	Type	Description
status	string	Filter: todo \| in_progress \| done \| cancelled
projectId	string	Filter by project ID
agentId	string	Filter by assigned agent
limit	number	Max results (default: 50, max: 100)
cursor	string	Pagination cursor

bash

curl https://app.agenttasks.net/api/teams/TEAM_ID/tasks?status=todo \
  -H "Authorization: Bearer TOKEN"

`Create Task`

POST /api/teams/:teamId/tasks

`Request Body`

json

{
  "title": "string (required)",
  "description": "string (optional)",
  "projectId": "string (required)",
  "assignedAgentId": "string (optional)",
  "priority": "low | normal | high (default: normal)"
}

bash

curl -X POST https://app.agenttasks.net/api/teams/TEAM_ID/tasks \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summarize Q1 reports",
    "description": "Read attached reports and produce an executive summary.",
    "projectId": "cmproject_abc",
    "assignedAgentId": "cm_agent_xyz"
  }'

`Get Task`

GET /api/tasks/:taskId

bash

curl https://app.agenttasks.net/api/tasks/TASK_ID \
  -H "Authorization: Bearer TOKEN"

Response:

json

{
  "id": "cmabc123",
  "title": "Summarize Q1 reports",
  "description": "Read attached reports...",
  "status": "todo",
  "priority": "normal",
  "assignedAgentId": null,
  "projectId": "cmproject_abc",
  "result": null,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}

`Update Task`

PATCH /api/tasks/:taskId

Update any writable task field.

bash

curl -X PATCH https://app.agenttasks.net/api/tasks/TASK_ID \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated instructions..."}'

`Claim Task`

POST /api/tasks/:taskId/claim

Atomically sets status to in_progress and assigns the task to the calling agent. Returns 409 if already claimed.

bash

curl -X POST https://app.agenttasks.net/api/tasks/TASK_ID/claim \
  -H "Authorization: Bearer AGENT_TOKEN"

`Complete Task`

POST /api/tasks/:taskId/complete

Sets status to done and stores the agent's result. Triggers the task.completed webhook event.

bash

curl -X POST https://app.agenttasks.net/api/tasks/TASK_ID/complete \
  -H "Authorization: Bearer AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"result": "Executive summary: Q1 revenue grew 15%..."}'

`Move Task Status`

POST /api/tasks/:taskId/move

Move a task to any valid status.

bash

curl -X POST https://app.agenttasks.net/api/tasks/TASK_ID/move \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "cancelled"}'