Tasks API

What this does

The Tasks API exposes the CRM's reminders module — the personal task list users see at /my-tasks and the related per-record task panels. Use it to set reminders from a bot ("remind me to chase Sarah on Friday"), pull a list of open tasks, or mark one done.

This is the underlying crm_tasks table — same entity used by in-app reminders, momentum mode, recurring tasks, and the daily reminders cron.

When to use it

Create a task from a bot conversation ("remind me to call John Tuesday at 9am").
Show a user their outstanding tasks via a chat command.
Mark a task complete after the user confirms the action.

Authentication and scopes

Requests must include Authorization: Bearer <key>. Each endpoint requires:

tasks:read — list tasks
tasks:write — create or complete a task

Endpoints

List tasks

GET /api/v1/tasks

Query parameters:

| Param | Notes | |---|---| | status | e.g. To Do, In Progress, Completed, Pending | | user_id | Filter to one assignee | | due_from / due_to | ISO date range filter on due_date | | page, limit | Pagination (default page=1, limit=50, max 100) |

Sorted by due_date ASC NULLS LAST, created_at DESC.

Response: { data: Task[], pagination: { page, limit, total, hasMore } }.

Create a task

POST /api/v1/tasks

{
  "title": "Call John Smith back",
  "user_id": "u_abc123",
  "due_date": "2026-05-15",
  "priority": "High",
  "description": "Confirm Tuesday delivery slot",
  "related_type": "contact",
  "related_id": "cnt_xyz"
}

title and user_id are both required (assignee_id is accepted as an alias for user_id; first wins). priority accepts Low, Medium, or High — anything else falls back to Medium. status defaults to "To Do" if unspecified. Optional: description, due_date (ISO date), related_type, related_id.

Response (201 Created): the created crm_tasks row.

Errors:

| Code | Status | Meaning | |---|---|---| | missing_field | 400 | title or user_id missing | | invalid_reference | 400 | user_id is not a valid user id (FK violation) | | task_failed | 400 | Other validation failure from the underlying service | | tasks_write_denied | 403 | API key lacks tasks:write |

Complete a task

PATCH /api/v1/tasks/:id/complete

No body required. Sets status = "Completed" on the task.

Response: the full updated task row.