API Documentation
Task Lists ¶
Task Lists ¶
The Task list object represents a task list within the project management system. It sits between Boards and Tasks, meaning it belongs to a board and contains multiple tasks.
You can find out more about task lists in our Help documentation: Task lists
Following diagram shows task lists in our data hierarchy:
Supported filter params
-
id
-
project_id (array)
-
board_id (array)
-
status (active: 1, archived: 2)
Supported relationship filter params
-
board
-
project
GET /api/v2/task_lists?filter[project_id]=1883
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": [
{
"id": "333",
"type": "task_lists",
"attributes": {
"name": "task list name",
"position": null,
"placement": null,
"archived_at": null,
"email_key": "016af8c10550f05beecb8e203285d460"
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1950"
}
},
"project": {
"meta": {
"included": false
}
},
"board": {
"meta": {
"included": false
}
},
"folder": {
"meta": {
"included": false
}
}
}
}
],
"links": {
"first": "http://api-test.productive.io/api/v2/task_lists?filter%5Bproject_id%5D=1883&page%5Bnumber%5D=1&page%5Bsize%5D=30",
"last": "http://api-test.productive.io/api/v2/task_lists?filter%5Bproject_id%5D=1883&page%5Bnumber%5D=1&page%5Bsize%5D=30"
},
"meta": {
"current_page": 1,
"total_pages": 1,
"total_count": 1,
"page_size": 30,
"max_page_size": 200
}
}
Get task listsGET/api/v2/task_lists
GET /api/v2/task_lists/336
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "336",
"type": "task_lists",
"attributes": {
"name": "task list name",
"position": null,
"placement": null,
"archived_at": null,
"email_key": "cc7bda21ec1ce58bdf235542b90a4107"
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1952"
}
},
"project": {
"meta": {
"included": false
}
},
"board": {
"meta": {
"included": false
}
},
"folder": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
POST /api/v2/task_lists
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "task_lists",
"attributes": {
"name": "test name"
},
"relationships": {
"project": {
"data": {
"type": "projects",
"id": "1888"
}
},
"board": {
"data": {
"type": "boards",
"id": "353"
}
}
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "338",
"type": "task_lists",
"attributes": {
"name": "test name",
"position": null,
"placement": null,
"archived_at": null,
"email_key": "0314f0daf1c57ee193b2263e89432152"
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1953"
}
},
"project": {
"meta": {
"included": false
}
},
"board": {
"meta": {
"included": false
}
},
"folder": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
POST /api/v2/task_lists
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "task_lists",
"attributes": {
"name": ""
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"errors": [
{
"status": "422",
"code": "invalid_attribute",
"title": "Invalid Attribute",
"detail": "can't be blank",
"source": {
"pointer": "data/attributes/name"
}
},
{
"status": "422",
"code": "invalid_attribute",
"title": "Invalid Attribute",
"detail": "can't be blank",
"source": {
"pointer": "data/attributes/project"
}
},
{
"status": "422",
"code": "invalid_attribute",
"title": "Invalid Attribute",
"detail": "can't be blank",
"source": {
"pointer": "data/attributes/board"
}
}
]
}
Create a task listPOST/api/v2/task_lists
- name
string
(required) Example: Namename
- project_id
number
(required) Example: 1project id
- board_id
number
(required) Example: 1board id
PATCH /api/v2/task_lists/341
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "task_lists",
"attributes": {
"name": "new name"
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "341",
"type": "task_lists",
"attributes": {
"name": "new name",
"position": null,
"placement": null,
"archived_at": null,
"email_key": "3e1e6114718a20cb3301c4a9cbddb5f8"
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1957"
}
},
"project": {
"meta": {
"included": false
}
},
"board": {
"meta": {
"included": false
}
},
"folder": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
Update a task listPATCH/api/v2/task_lists/{id}
- id
number
(required) Example: 1task list id
PATCH /api/v2/task_lists/342/archive
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "342",
"type": "task_lists",
"attributes": {
"name": "task list name",
"position": null,
"placement": null,
"archived_at": "2025-08-01T06:18:17.000+02:00",
"email_key": "958e48d298a4c78a650ba77b744cea51"
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1958"
}
},
"project": {
"meta": {
"included": false
}
},
"board": {
"meta": {
"included": false
}
},
"folder": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
Archives a task listPATCH/api/v2/task_lists/{id}/archive
- id
number
(required) Example: 1task list id
PATCH /api/v2/task_lists/343/restore
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "343",
"type": "task_lists",
"attributes": {
"name": "Milestone323",
"position": null,
"placement": 1010000,
"archived_at": null,
"email_key": "92c054a63d4e69372bccc40d00b3572b"
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1959"
}
},
"project": {
"meta": {
"included": false
}
},
"board": {
"meta": {
"included": false
}
},
"folder": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
Restores a task listPATCH/api/v2/task_lists/{id}/restore
- id
number
(required) Example: 1task list id
POST /api/v2/task_lists/copy
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "task_lists",
"attributes": {
"name": "copy task list",
"template_id": 344,
"project_id": 1894,
"board_id": 359,
"copy_open_tasks": true,
"copy_assignees": true
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "345",
"type": "task_lists",
"attributes": {
"name": "copy task list",
"position": null,
"placement": null,
"archived_at": null,
"email_key": "003d22c85edfa72b9363a3abc3d71c35"
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1960"
}
},
"project": {
"meta": {
"included": false
}
},
"board": {
"meta": {
"included": false
}
},
"folder": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
POST /api/v2/task_lists/copy
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "task_lists",
"attributes": {
"name": "copy task list",
"template_id": 346,
"project_id": 1896,
"board_id": 361,
"copy_open_tasks": true,
"copy_assignees": true
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "347",
"type": "task_lists",
"attributes": {
"name": "copy task list",
"position": null,
"placement": null,
"archived_at": null,
"email_key": "45968993a426ad19524be2f814be2f5a"
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1961"
}
},
"project": {
"meta": {
"included": false
}
},
"board": {
"meta": {
"included": false
}
},
"folder": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
POST /api/v2/task_lists/copy
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "task_lists",
"attributes": {
"name": "copy task list",
"template_id": 348,
"project_id": 1898,
"board_id": 363,
"copy_open_tasks": true,
"copy_assignees": true
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "350",
"type": "task_lists",
"attributes": {
"name": "copy task list",
"position": null,
"placement": null,
"archived_at": null,
"email_key": "c222e8c2d155d5dc65bfecf3eab9fa3a"
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1962"
}
},
"project": {
"meta": {
"included": false
}
},
"board": {
"meta": {
"included": false
}
},
"folder": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
POST /api/v2/task_lists/copy
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "task_lists",
"attributes": {
"name": "copy task list",
"template_id": 351,
"project_id": 1903,
"board_id": 366,
"copy_open_tasks": true,
"copy_assignees": true
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "353",
"type": "task_lists",
"attributes": {
"name": "copy task list",
"position": null,
"placement": null,
"archived_at": null,
"email_key": "1645bdd169040f112be184ed3675163f"
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1963"
}
},
"project": {
"meta": {
"included": false
}
},
"board": {
"meta": {
"included": false
}
},
"folder": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
Copies a task listPOST/api/v2/task_lists/copy
- id
number
(required) Example: 1task list id
PATCH /api/v2/task_lists/354/move
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "task_lists",
"attributes": {
"board_id": 369
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "354",
"type": "task_lists",
"attributes": {
"name": "task list name",
"position": null,
"placement": null,
"archived_at": null,
"email_key": "738e707df18c07025423b8f473f934bc"
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1964"
}
},
"project": {
"meta": {
"included": false
}
},
"board": {
"meta": {
"included": false
}
},
"folder": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
PATCH /api/v2/task_lists/355/move
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "task_lists",
"attributes": {
"board_id": ""
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"errors": [
{
"status": "422",
"code": "invalid_attribute",
"title": "Invalid Attribute",
"detail": "attribute is invalid",
"source": {
"pointer": "data/attributes/board_id"
}
}
]
}
Moves a task listPATCH/api/v2/task_lists/{id}/move
- id
number
(required) Example: 1task list id
PATCH /api/v2/task_lists/356/reposition
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "task_lists",
"attributes": {
"move_before_id": 357
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "356",
"type": "task_lists",
"attributes": {
"name": "task list name",
"position": null,
"placement": 90000,
"archived_at": null,
"email_key": "90284e0f4830249623384b2b379a556d"
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "1966"
}
},
"project": {
"meta": {
"included": false
}
},
"board": {
"meta": {
"included": false
}
},
"folder": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
Repoisition a task listPATCH/api/v2/task_lists/{id}/reposition
- id
number
(required) Example: 1task list id
Generated by aglio on 01 Aug 2025