List Tasks

List and filter tasks you have access to.

GET /api/v1/tasks

cURL

curl --location --request GET 'https://api.wordsmith.ai/api/v1/tasks' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response

{
  "items": [
    {
      "id": "9f8e7d6c-5b4a-3210-9876-543210fedcba",
      "display_id": "#12",
      "task_number": 12,
      "title": "Review the Acme NDA",
      "description": "Check the indemnity and termination clauses.",
      "additional_context": "Counterparty has pushed back twice on liability caps.",
      "status": "in_progress",
      "priority": "high",
      "team": {
        "id": "1a2b3c4d-5e6f-7081-9200-aabbccddeeff",
        "name": "Legal"
      },
      "creator": {
        "id": "11111111-2222-3333-4444-555555555555",
        "name": "Jane Doe",
        "email": "[e-mail]"
      },
      "assigned_to": {
        "id": "11111111-2222-3333-4444-555555555555",
        "name": "Jane Doe",
        "email": "[e-mail]"
      },
      "assigned_agent": null,
      "assigned_team": null,
      "matter": null,
      "complete_by": "2026-01-01T00:00:00Z",
      "tags": [
        "nda",
        "urgent"
      ],
      "source_channel": "web",
      "visibility": "customer",
      "archived": false,
      "draft": false,
      "involved_people": [
        {
          "id": "11111111-2222-3333-4444-555555555555",
          "name": "Jane Doe",
          "email": "[e-mail]",
          "role": "assignee",
          "access_level": "write"
        }
      ],
      "shared_teams": [],
      "linked_items": [],
      "input_files": [],
      "output_files": [],
      "created_at": "2025-12-31T00:00:00Z",
      "updated_at": "2025-12-31T01:00:00Z"
    }
  ],
  "cursor": "20"
}

Returns a cursor-paginated page of tasks, ordered by priority, then due date, then most recently created. Filtering by status=completed alone is the exception: finished work comes back most recently completed first, since priority order there buries the latest completions. Results are scoped to what your API key’s user can see.

Pass the cursor from a response to fetch the next page; a null cursor means you have reached the end. Keep limit the same for every page of a walk — the cursor is tied to the page size it was issued with, so changing it mid-walk skips or repeats rows. Archived and draft tasks are excluded unless you filter for them.

assigned_to and involving take a user id, email address or name. A user id is applied as given, so the tasks of a deactivated user stay listable. An email or name that matches nobody, or more than one person, is a 400 rather than an empty page; the ambiguous case lists the candidates.

When an item has an agent assigned, assigned_agent.id is the agent’s record id and assigned_agent.counsel_id is the agent id List Agents returns; either is accepted wherever an agent is referenced. counsel_id added 2026-09-05.

Query parameters

query · string

Free-text search across title, description, additional context and comment text.

status · string

Comma-separated: not_started, in_progress, waiting_on_external, completed.

priority · string

One of no_priority, urgent, high, medium, low.

assigned_to · string

A user id, email address, or name — only tasks assigned to this person.

involving · string

A user id, email address, or name — tasks this person is involved in at all (assignee, creator or shared).

team_id · string

Task team id.

tags · string

Comma-separated tag list.

source_channel · string

Comma-separated source groups — only tasks that came in through any of them: email (forwarding address and connected mailboxes), slack, teams, whatsapp, web_app (web, iOS, Android, Office add-ins, template drafting, report and playbook chats), api, scheduled, agent (created by an agent run, RSS or an evaluation). An unknown value is a 400. Each task’s raw channel is returned in source_channel.

complete_by_from · string

ISO 8601 timestamp, e.g. 2026-01-01 or 2026-01-01T09:00:00Z — only tasks due at or after it.

complete_by_to · string

ISO 8601 timestamp — only tasks due at or before it.

cursor · string

Pagination cursor from a previous response.

limit · string

Page size, 1–100. Defaults to 20. Values below 1 are rejected.

cURL

curl --location --request GET 'https://api.wordsmith.ai/api/v1/tasks' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response

{
  "items": [
    {
      "id": "9f8e7d6c-5b4a-3210-9876-543210fedcba",
      "display_id": "#12",
      "task_number": 12,
      "title": "Review the Acme NDA",
      "description": "Check the indemnity and termination clauses.",
      "additional_context": "Counterparty has pushed back twice on liability caps.",
      "status": "in_progress",
      "priority": "high",
      "team": {
        "id": "1a2b3c4d-5e6f-7081-9200-aabbccddeeff",
        "name": "Legal"
      },
      "creator": {
        "id": "11111111-2222-3333-4444-555555555555",
        "name": "Jane Doe",
        "email": "[e-mail]"
      },
      "assigned_to": {
        "id": "11111111-2222-3333-4444-555555555555",
        "name": "Jane Doe",
        "email": "[e-mail]"
      },
      "assigned_agent": null,
      "assigned_team": null,
      "matter": null,
      "complete_by": "2026-01-01T00:00:00Z",
      "tags": [
        "nda",
        "urgent"
      ],
      "source_channel": "web",
      "visibility": "customer",
      "archived": false,
      "draft": false,
      "involved_people": [
        {
          "id": "11111111-2222-3333-4444-555555555555",
          "name": "Jane Doe",
          "email": "[e-mail]",
          "role": "assignee",
          "access_level": "write"
        }
      ],
      "shared_teams": [],
      "linked_items": [],
      "input_files": [],
      "output_files": [],
      "created_at": "2025-12-31T00:00:00Z",
      "updated_at": "2025-12-31T01:00:00Z"
    }
  ],
  "cursor": "20"
}