Tasks API

Tasks are the core work unit in profClaw. They are created from webhooks, the API, or the UI, queued for agent execution, and tracked through their lifecycle.

Task Status

pending -> queued -> in_progress -> completed | failed | cancelled

GET /api/tasks

List tasks with optional status filter and pagination.

curl "http://localhost:3000/api/tasks?status=pending&limit=20" \
  --cookie "profclaw_session=<token>"

Query parameters

Param	Type	Description
`status`	string	Filter by status
`limit`	number	Max results (default 50)
`offset`	number	Offset for pagination
`cursor`	string	Cursor for cursor-based pagination (preferred)
`fields`	string	Comma-separated sparse fieldset
`full`	boolean	Return full objects (disables sparse fieldset)

Response 200

{
  "tasks": [
    {
      "id": "task_01",
      "title": "Fix login bug",
      "status": "pending",
      "priority": 2,
      "source": "github",
      "sourceId": "42",
      "sourceUrl": "https://github.com/org/repo/issues/42",
      "labels": ["bug"],
      "assignedAgent": "claude-code",
      "createdAt": "2026-03-12T10:00:00Z"
    }
  ],
  "total": 142,
  "count": 20,
  "limit": 20,
  "nextCursor": "eyJjcmVhdGVkQXQiOjE3MDAwMDAwMDAsImlkIjoiMDEifQ"
}

POST /api/tasks

Create a new task.

curl -X POST http://localhost:3000/api/tasks \
  -H "Content-Type: application/json" \
  --cookie "profclaw_session=<token>" \
  -d '{
    "title": "Add dark mode",
    "description": "Implement dark mode for the settings page",
    "prompt": "Add a dark mode toggle to the settings page using Tailwind CSS",
    "priority": 3,
    "source": "api",
    "labels": ["ui", "feature"]
  }'

Request body (validated with CreateTaskSchema)

Field	Type	Required	Notes
`title`	string	Yes
`description`	string	No
`prompt`	string	No	Detailed instructions for the agent
`priority`	number	No	1 (critical) - 4 (low)
`source`	string	No	`github` \| `jira` \| `linear` \| `api` \| `cron`
`sourceId`	string	No	External ID
`sourceUrl`	string	No	Link back to source
`repository`	string	No	`owner/repo`
`branch`	string	No	Git branch
`labels`	string[]	No
`assignedAgent`	string	No	Force a specific adapter

Response 201: { "message": "Task created", "task": {...} }

GET /api/tasks/:id

Fetch a single task by ID.

POST /api/tasks/:id/cancel

Cancel a pending or in-progress task.

curl -X POST http://localhost:3000/api/tasks/task_01/cancel

Response 200: { "message": "Task cancelled", "task": {...} }

POST /api/tasks/:id/retry

Retry a failed or completed task. Creates a new task with the same parameters.

curl -X POST http://localhost:3000/api/tasks/task_01/retry

Response 200: { "message": "Task queued for retry", "task": {...}, "originalTaskId": "task_01" }

GET /api/tasks/:id/events

Retrieve the audit event log for a task (requires storage.getTaskEvents).

Advanced Filtering

GET /api/tasks/filter?status=failed,completed&priority=1,2&source=github&q=login

Supported params: status, priority, source, agent, labels, createdAfter, createdBefore, completedAfter, completedBefore, repository, q, sortBy, sortOrder

Analytics

GET /api/tasks/analytics

Returns aggregated statistics: counts by status, average durations, failure rates, and source breakdown.

Export / Import

# Export all tasks as JSON
GET /api/tasks/export

# Import from a previous export
POST /api/tasks/import
Content-Type: application/json
{ "version": "1.0", "tasks": [...] }

Task Queue API - Inspect queue depth and manage dead-letter entries
Agent Sessions API - Monitor task execution sessions
profclaw task - Create and manage tasks from the CLI
Webhooks API - Receive tasks from GitHub, Jira, and Linear

API Overview

Authentication

Chat

Agents

Tasks

Memory

Integrations

System

Task Status

GET /api/tasks

POST /api/tasks

GET /api/tasks/:id

POST /api/tasks/:id/cancel

POST /api/tasks/:id/retry

GET /api/tasks/:id/events

Advanced Filtering

Analytics

Export / Import

​Task Status

​GET /api/tasks

​POST /api/tasks

​GET /api/tasks/:id

​POST /api/tasks/:id/cancel

​POST /api/tasks/:id/retry

​GET /api/tasks/:id/events

​Advanced Filtering

​Analytics

​Export / Import

​Related

Task Status

GET /api/tasks

POST /api/tasks

GET /api/tasks/:id

POST /api/tasks/:id/cancel

POST /api/tasks/:id/retry

GET /api/tasks/:id/events

Advanced Filtering

Analytics

Export / Import

Related