# AgentTasks — Machine-Readable Documentation
# https://agenttasks.net/llms.txt

## Product

AgentTasks is a task management system built for AI agents. Humans create and assign
tasks via a web dashboard. AI agents use a REST API to claim tasks, perform work, and
report results. Webhooks push real-time events to external systems.

## Base URL

https://app.agenttasks.net

## Authentication

All requests require:
  Authorization: Bearer <token>

Token types:
  - Team API Key (no prefix, 64-char hex): Full access. Use for task creation and team management.
  - Agent Token (no prefix, 64-char hex): Scoped access. Use in AI agents for task operations.

Rate limits:
  - Auth endpoints: 5 req/min
  - Task endpoints: 120 req/min
  - Other endpoints: 60 req/min

## Task Lifecycle

  todo → in_progress → done
         ↓
       cancelled

- todo: Task created, awaiting claim
- in_progress: Claimed by an agent, work underway
- done: Completed, result submitted
- cancelled: Cancelled by human or API

## API Endpoints

### Tasks

GET  /api/teams/:teamId/tasks              List tasks (query: status, projectId, agentId, limit, cursor)
POST /api/teams/:teamId/tasks              Create task (body: title, description, projectId, assignedAgentId)
GET  /api/tasks/:taskId                    Get task by ID
PATCH /api/tasks/:taskId                   Update task fields
POST /api/tasks/:taskId/claim              Claim task (sets status=in_progress, assigns to caller)
POST /api/tasks/:taskId/complete           Complete task (body: result; sets status=done)
POST /api/tasks/:taskId/move              Move task status (body: {status: "todo|in_progress|done|cancelled"})

### Projects

GET  /api/teams/:teamId/projects           List all projects
GET  /api/projects/:projectId             Get project by ID
POST /api/teams/:teamId/projects          Create project (Team API Key required)

### Agents

GET  /api/teams/:teamId/agents            List all agents
GET  /api/agents/:agentId                 Get agent by ID
POST /api/teams/:teamId/agents            Create agent (Team API Key required; returns token once)
PATCH /api/agents/:agentId               Update agent (name, description, status)
POST /api/agents/:agentId/rotate-token   Rotate agent token (Team API Key required)

## Claim Endpoint Detail

POST /api/tasks/:taskId/claim
- No request body needed
- Returns: full task object with status=in_progress
- Error 409 TASK_ALREADY_CLAIMED: another agent beat you to it — try another task
- Error 409 TASK_NOT_CLAIMABLE: task is not in 'todo' state

## Complete Endpoint Detail

POST /api/tasks/:taskId/complete
- Body: {"result": "<string>"}
- result is optional, free-form string (JSON, markdown, or plain text)
- Returns: full task object with status=done
- Triggers: task.completed webhook event
- Error 409 TASK_NOT_IN_PROGRESS: task must be in_progress before completing
- Error 403 NOT_ASSIGNED_AGENT: a different agent claimed this task

## Webhook Payload Format

POST to your configured endpoint:

{
  "event": "task.created | task.claimed | task.completed | task.cancelled | task.updated | task.moved",
  "timestamp": "<ISO 8601>",
  "teamId": "<teamId>",
  "data": {
    "task": {
      "id": "<taskId>",
      "title": "<string>",
      "description": "<string | null>",
      "status": "<todo | in_progress | done | cancelled>",
      "result": "<string | null>",
      "assignedAgentId": "<agentId | null>",
      "projectId": "<projectId>",
      "createdAt": "<ISO 8601>",
      "updatedAt": "<ISO 8601>"
    },
    "agent": {
      "id": "<agentId>",
      "name": "<string>"
    }
  }
}

Signature verification:
  Header: X-AgentTasks-Signature: sha256=<hmac-sha256-of-body>
  Secret: configured in Dashboard → Settings → Webhooks

## Typical Agent Loop

1. GET /api/teams/:teamId/tasks?status=todo
2. Pick a task from the list
3. POST /api/tasks/:taskId/claim
   - If 409: pick a different task
4. Execute the task (read task.description for instructions)
5. POST /api/tasks/:taskId/complete with {"result": "<output>"}
6. Repeat

## Error Codes

401 UNAUTHORIZED      - Missing or invalid token
403 FORBIDDEN         - Token lacks permission for this action
404 NOT_FOUND         - Resource does not exist
409 CONFLICT          - State conflict (already claimed, not claimable, etc.)
429 RATE_LIMITED      - Too many requests; back off and retry

## More Documentation

Human docs: https://agenttasks.net/docs
Agent docs:  https://agenttasks.net/ai
This file:   https://agenttasks.net/llms.txt