API reference

Tasks

Tasks are the work to be done: a title, a status, dates, an owner and assignees, optionally linked to a contact, a deal or a project. Every plan includes them.

Scopes: tasks:read · tasks:write
Plan: Every plan
Events: task.*

The task object

A task lives in a task space — a board with its own columns. status is the simple, portable state; status_category tells you what the task’s column means on its board.

Attributes

iduuidRead-only
Unique identifier of the task.
titlestring
What needs doing.
descriptionstringNullable
More detail.
statusenum
Progress. Writing it also moves the task to a matching column on its board.
One oftodoin_progressdone
status_categoryenumRead-onlyNullable
The kind of board column the task is in. Boards can have their own columns; this tells you what a column means. null when the task is not on a board column.
One ofbacklogunstartedstartedcompletedcanceled
prioritystringNullable
Priority: low, medium, high, or one of the workspace’s own priority keys; null for none.
due_datedate-timeNullable
When the task is due (UTC). A date alone (YYYY-MM-DD) is accepted and stored as midnight UTC.
start_datedate-timeNullable
When work starts (UTC). A date alone is accepted, as for due_date.
completed_atdate-timeRead-onlyNullable
When the status became done.
project_iduuidNullable
The project the task belongs to.
space_iduuidNullable
The task space (board) that holds the task. Defaults to the workspace’s default space.
parent_task_iduuidNullable
The parent task, for subtasks.
contact_iduuidNullable
A related contact.
deal_iduuidNullable
A related deal.
owner_iduuid
The user who owns the record. On create it defaults to the API key’s owner. See Users.
assignee_idsuuid[]
Users the task is assigned to. Writing it replaces the list.
custom_fieldsobject
Custom-field values keyed by field key. Updates merge into the stored values; send null for a key to clear it. See Custom fields.
created_atdate-timeRead-only
When the record was created (UTC).
updated_atdate-timeRead-only
When the record last changed (UTC).

The task object

{
  "id": "c5a3e7f1-9d2b-4c6a-8e4f-1b3d5f7a9c26",
  "title": "Send the renewal proposal",
  "description": "Two options: annual at 40 seats, or a 24-month term with onboarding included.",
  "status": "in_progress",
  "status_category": "started",
  "priority": "high",
  "due_date": "2026-10-15T15:00:00Z",
  "start_date": "2026-10-10T08:00:00Z",
  "completed_at": null,
  "project_id": null,
  "space_id": "e1b7d3f9-5a2c-4e8b-9d6f-3a5c7e9b1d48",
  "parent_task_id": null,
  "contact_id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
  "deal_id": "8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80",
  "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
  "assignee_ids": [
    "6a2d9c4e-1f8b-4e3a-b7d5-9c0e2f4a6b18"
  ],
  "custom_fields": {},
  "created_at": "2026-10-09T15:42:10Z",
  "updated_at": "2026-10-10T08:05:37Z"
}

Status and board columns

Boards can have columns of their own, such as “In review” or “Blocked”. The API speaks three statuses, and keeps the board in step: writing status moves the task to a matching column, and moving it on the board changes status.

`status`	Board column kind (`status_category`)
`todo`	`backlog` or `unstarted`
`in_progress`	`started`
`done`	`completed` or `canceled`

When a task becomes done — its status set to done, or the task moved to a done column — completed_at is filled and Nextora sends task.completed.

Subtasks

A subtask is a task with parent_task_id. Set it when you create the subtask; it cannot change afterwards. Lists include subtasks — filter with parent_task_id=null for top-level tasks only, or parent_task_id=<id> for the subtasks of one task.

List the subtasks of a task

curl -G https://acme.nextora.co/api/v1/tasks \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -d parent_task_id=c5a3e7f1-9d2b-4c6a-8e4f-1b3d5f7a9c26

List tasks

GET/api/v1/tasks

Requires tasks:read

Returns the tasks the key’s owner can see, newest first — subtasks included. Filter on the fields below, combine them with q, and follow meta.next_cursor for more.

Query parameters

limitinteger
Page size, from 1 to 100.
Default50
cursorstring
The meta.next_cursor of the previous page. Omit it for the first page.
qstring
Search by title.
sortenum
The field to sort by. Any other value is a 400 validation_failed.
One ofcreated_atupdated_attitledue_datestart_dateprioritycompleted_at
Defaultcreated_at
orderenum
Sort direction.
One ofascdesc
Defaultdesc
filterstring (JSON)
An advanced filter: conditions joined with and or or. See the JSON filter.

Filters

Add ?field=value or ?field[operator]=value — operators.

statusenum
Exact match, or several values with [in].
One oftodoin_progressdone
prioritystring
Exact match. [like] matches a case-insensitive substring.
owner_iduuid
Exact match, or several IDs with [in].
contact_iduuid
Exact match, or several IDs with [in].
deal_iduuid
Exact match, or several IDs with [in].
project_iduuid
Exact match, or several IDs with [in].
space_iduuid
Exact match, or several IDs with [in].
parent_task_iduuid
null returns top-level tasks only. Exact match, or several IDs with [in].
due_datedate-time
An ISO 8601 timestamp. Use a range: [gt], [gte], [lt], [lte].
start_datedate-time
An ISO 8601 timestamp. Use a range: [gt], [gte], [lt], [lte].
created_atdate-time
An ISO 8601 timestamp. Use a range: [gt], [gte], [lt], [lte].
updated_atdate-time
An ISO 8601 timestamp. Use a range: [gt], [gte], [lt], [lte].

Returns

A list of task objects and meta. meta.next_cursor is null on the last page.

GET/api/v1/tasks

curl -G https://acme.nextora.co/api/v1/tasks \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -d owner_id=0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47 \
  -d status=in_progress \
  -d 'due_date[lte]=2026-10-17' \
  -d sort=due_date \
  -d order=asc

Response200 OK

{
  "data": [
    {
      "id": "c5a3e7f1-9d2b-4c6a-8e4f-1b3d5f7a9c26",
      "title": "Send the renewal proposal",
      "description": "Two options: annual at 40 seats, or a 24-month term with onboarding included.",
      "status": "in_progress",
      "status_category": "started",
      "priority": "high",
      "due_date": "2026-10-15T15:00:00Z",
      "start_date": "2026-10-10T08:00:00Z",
      "completed_at": null,
      "project_id": null,
      "space_id": "e1b7d3f9-5a2c-4e8b-9d6f-3a5c7e9b1d48",
      "parent_task_id": null,
      "contact_id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
      "deal_id": "8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80",
      "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
      "assignee_ids": [
        "6a2d9c4e-1f8b-4e3a-b7d5-9c0e2f4a6b18"
      ],
      "custom_fields": {},
      "created_at": "2026-10-09T15:42:10Z",
      "updated_at": "2026-10-10T08:05:37Z"
    }
  ],
  "meta": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}

Create a task

POST/api/v1/tasks

Requires tasks:write

Creates a task. It goes through the same path as the app, so workflows, the activity log and webhooks behave as they do for a task created by hand.

Body parameters

titlestringRequired
What needs doing.
descriptionstringNullable
More detail.
statusenum
Progress. Writing it also moves the task to a matching column on its board.
One oftodoin_progressdone
Defaulttodo
prioritystringNullable
Priority: low, medium, high, or one of the workspace’s own priority keys; null for none.
due_datedate-timeNullable
When the task is due (UTC). A date alone (YYYY-MM-DD) is accepted and stored as midnight UTC.
start_datedate-timeNullable
When work starts (UTC). A date alone is accepted, as for due_date.
project_iduuidNullable
The project the task belongs to.
parent_task_iduuidCreate onlyNullable
Makes the task a subtask of this task. Set on create only.
space_iduuidNullable
The task space (board) that holds the task. Defaults to the workspace’s default space.
contact_iduuidNullable
A related contact.
deal_iduuidNullable
A related deal.
owner_iduuid
The user who owns the record. On create it defaults to the API key’s owner. See Users.
assignee_idsuuid[]
Users the task is assigned to. Writing it replaces the list.

Returns

The new task, with 201 Created.

POST/api/v1/tasks

curl -X POST https://acme.nextora.co/api/v1/tasks \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Send the renewal proposal",
    "description": "Two options: annual at 40 seats, or a 24-month term with onboarding included.",
    "priority": "high",
    "due_date": "2026-10-15",
    "start_date": "2026-10-10",
    "contact_id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
    "deal_id": "8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80",
    "assignee_ids": [
      "6a2d9c4e-1f8b-4e3a-b7d5-9c0e2f4a6b18"
    ]
  }'

Response201 Created

{
  "data": {
    "id": "c5a3e7f1-9d2b-4c6a-8e4f-1b3d5f7a9c26",
    "title": "Send the renewal proposal",
    "description": "Two options: annual at 40 seats, or a 24-month term with onboarding included.",
    "status": "todo",
    "status_category": "unstarted",
    "priority": "high",
    "due_date": "2026-10-15T15:00:00Z",
    "start_date": "2026-10-10T08:00:00Z",
    "completed_at": null,
    "project_id": null,
    "space_id": "e1b7d3f9-5a2c-4e8b-9d6f-3a5c7e9b1d48",
    "parent_task_id": null,
    "contact_id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
    "deal_id": "8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80",
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "assignee_ids": [
      "6a2d9c4e-1f8b-4e3a-b7d5-9c0e2f4a6b18"
    ],
    "custom_fields": {},
    "created_at": "2026-10-10T08:05:37Z",
    "updated_at": "2026-10-10T08:05:37Z"
  }
}

Retrieve a task

GET/api/v1/tasks/{id}

Requires tasks:read

Returns one task by ID.

Path parameters

iduuidRequired
The task’s ID.

Returns

The task. 404 not_found when it does not exist or the key’s owner cannot see it.

GET/api/v1/tasks/{id}

curl https://acme.nextora.co/api/v1/tasks/c5a3e7f1-9d2b-4c6a-8e4f-1b3d5f7a9c26 \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "c5a3e7f1-9d2b-4c6a-8e4f-1b3d5f7a9c26",
    "title": "Send the renewal proposal",
    "description": "Two options: annual at 40 seats, or a 24-month term with onboarding included.",
    "status": "in_progress",
    "status_category": "started",
    "priority": "high",
    "due_date": "2026-10-15T15:00:00Z",
    "start_date": "2026-10-10T08:00:00Z",
    "completed_at": null,
    "project_id": null,
    "space_id": "e1b7d3f9-5a2c-4e8b-9d6f-3a5c7e9b1d48",
    "parent_task_id": null,
    "contact_id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
    "deal_id": "8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80",
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "assignee_ids": [
      "6a2d9c4e-1f8b-4e3a-b7d5-9c0e2f4a6b18"
    ],
    "custom_fields": {},
    "created_at": "2026-10-09T15:42:10Z",
    "updated_at": "2026-10-10T08:05:37Z"
  }
}

Update a task

PATCH/api/v1/tasks/{id}

Requires tasks:write

Changes the fields you send and leaves the rest as they are. PUT does the same as PATCH.

Path parameters

iduuidRequired
The task’s ID.

Body parameters

titlestring
What needs doing.
descriptionstringNullable
More detail.
statusenum
Progress. Writing it also moves the task to a matching column on its board.
One oftodoin_progressdone
prioritystringNullable
Priority: low, medium, high, or one of the workspace’s own priority keys; null for none.
due_datedate-timeNullable
When the task is due (UTC). A date alone (YYYY-MM-DD) is accepted and stored as midnight UTC.
start_datedate-timeNullable
When work starts (UTC). A date alone is accepted, as for due_date.
project_iduuidNullable
The project the task belongs to.
space_iduuidNullable
The task space (board) that holds the task. Defaults to the workspace’s default space.
contact_iduuidNullable
A related contact.
deal_iduuidNullable
A related deal.
owner_iduuid
The user who owns the record. On create it defaults to the API key’s owner. See Users.
assignee_idsuuid[]
Users the task is assigned to. Writing it replaces the list.

Returns

The updated task.

PATCH/api/v1/tasks/{id}

curl -X PATCH https://acme.nextora.co/api/v1/tasks/c5a3e7f1-9d2b-4c6a-8e4f-1b3d5f7a9c26 \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "done"
  }'

Response200 OK

{
  "data": {
    "id": "c5a3e7f1-9d2b-4c6a-8e4f-1b3d5f7a9c26",
    "title": "Send the renewal proposal",
    "description": "Two options: annual at 40 seats, or a 24-month term with onboarding included.",
    "status": "done",
    "status_category": "completed",
    "priority": "high",
    "due_date": "2026-10-15T15:00:00Z",
    "start_date": "2026-10-10T08:00:00Z",
    "completed_at": "2026-10-10T16:20:12Z",
    "project_id": null,
    "space_id": "e1b7d3f9-5a2c-4e8b-9d6f-3a5c7e9b1d48",
    "parent_task_id": null,
    "contact_id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
    "deal_id": "8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80",
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "assignee_ids": [
      "6a2d9c4e-1f8b-4e3a-b7d5-9c0e2f4a6b18"
    ],
    "custom_fields": {},
    "created_at": "2026-10-09T15:42:10Z",
    "updated_at": "2026-10-10T16:20:12Z"
  }
}

Delete a task

DELETE/api/v1/tasks/{id}

Requires tasks:write

Moves the task to the workspace Trash, as deleting it in the app does. It disappears from lists; restore it to bring it back.

Path parameters

iduuidRequired
The task’s ID.

Returns

{ "data": { "id": "…", "deleted": true } }. 404 not_found when there is nothing to delete.

DEL/api/v1/tasks/{id}

curl -X DELETE https://acme.nextora.co/api/v1/tasks/c5a3e7f1-9d2b-4c6a-8e4f-1b3d5f7a9c26 \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "c5a3e7f1-9d2b-4c6a-8e4f-1b3d5f7a9c26",
    "deleted": true
  }
}

Restore a task

POST/api/v1/tasks/{id}/restore

Requires tasks:write

Brings a task back from Trash, with its fields and links as they were.

Path parameters

iduuidRequired
The task’s ID.

Returns

The restored task.

POST/api/v1/tasks/{id}/restore

curl -X POST https://acme.nextora.co/api/v1/tasks/c5a3e7f1-9d2b-4c6a-8e4f-1b3d5f7a9c26/restore \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "c5a3e7f1-9d2b-4c6a-8e4f-1b3d5f7a9c26",
    "title": "Send the renewal proposal",
    "description": "Two options: annual at 40 seats, or a 24-month term with onboarding included.",
    "status": "in_progress",
    "status_category": "started",
    "priority": "high",
    "due_date": "2026-10-15T15:00:00Z",
    "start_date": "2026-10-10T08:00:00Z",
    "completed_at": null,
    "project_id": null,
    "space_id": "e1b7d3f9-5a2c-4e8b-9d6f-3a5c7e9b1d48",
    "parent_task_id": null,
    "contact_id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
    "deal_id": "8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80",
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "assignee_ids": [
      "6a2d9c4e-1f8b-4e3a-b7d5-9c0e2f4a6b18"
    ],
    "custom_fields": {},
    "created_at": "2026-10-09T15:42:10Z",
    "updated_at": "2026-10-10T08:05:37Z"
  }
}