Tasks

Create, update, and track tasks with assignments and due dates

Endpoints

GET/v1/lists/{list_id}/tasks
POST/v1/lists/{list_id}/tasks
GET/v1/projects/{project_id}/tasks
GET/v1/tasks/my/assigned
GET/v1/tasks/{task_id}
PATCH/v1/tasks/{task_id}
PATCH/v1/tasks/{task_id}/complete

List list tasks

GET/v1/lists/{list_id}/tasks

Returns a collection of tasks for the given list.

Results can be filtered by assignee (all/assigned/unassigned) and updated[start]/updated[stop] time range.

Parameters

Name	In	Type	Description
page_start_id	query	integer (int32)	The page start ID.
page_limit	query	integer (int32)	The default page size
removed	query	boolean
list_idrequired	path	integer (int32)	A list ID

Responses

200A list of tasks

object

tasksarray
array<object>
items
object
task model
- idinteger
- subjectstring
- descriptionstring
- author_idinteger
- assignee_idsarray
  array<integer>
  items
  integer(int32)
- estimate_hoursnumber
- follower_idsarray
  array<integer>
  items
  integer(int32)
- mention_idsarray
  array<integer>
  items
  integer(int32)
- label_idsarray
  array<integer>
  items
  integer(int32)
- positioninteger
- list_idinteger
- doneboolean
- statusstring
- listobject
  object
  list model
  idinteger
  namestring
  project_idinteger
  positioninteger
  task_countinteger
  typestring
  created_atstring
  updated_atstring
- start_onstring
- due_onstring
- due_atstring
- done_atstring
- created_atstring
- updated_atstring

Example response

json

{
  "tasks": [
    {
      "id": 0,
      "subject": "string",
      "description": "string",
      "author_id": 0,
      "assignee_ids": [
        0
      ],
      "estimate_hours": 0,
      "follower_ids": [
        0
      ],
      "mention_ids": [
        0
      ],
      "label_ids": [
        0
      ],
      "position": 0,
      "list_id": 0,
      "done": false,
      "status": "string",
      "list": {
        "id": 0,
        "name": "string",
        "project_id": 0,
        "position": 0,
        "task_count": 0,
        "type": "string",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      },
      "start_on": "2024-01-15",
      "due_on": "2024-01-15",
      "due_at": "2024-01-15T10:30:00Z",
      "done_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}

400Invalid parameters

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

401Unauthorized

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

403API access is only for organizations on an active plan

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

404Could not find record

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

429Rate limit exceeded

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

Create task

POST/v1/lists/{list_id}/tasks

Creates a new task in the given list.

Returns the created task.

Parameters

Name	In	Type	Description
list_idrequired	path	integer (int32)	A list ID

Request body

object

task[subject]string required
task[description]string
task[due_on]string
task[due_at]string
task[estimate_hours]number
task[assignee_ids]array
array
task[assigned_to_id]integer
task[label_ids]array
array
task[follower_ids]array
array

Responses

201A task

object

taskobject
object
task model
- idinteger
- subjectstring
- descriptionstring
- author_idinteger
- assignee_idsarray
  array<integer>
  items
  integer(int32)
- estimate_hoursnumber
- follower_idsarray
  array<integer>
  items
  integer(int32)
- mention_idsarray
  array<integer>
  items
  integer(int32)
- label_idsarray
  array<integer>
  items
  integer(int32)
- positioninteger
- list_idinteger
- doneboolean
- statusstring
- listobject
  object
  list model
  - idinteger
  - namestring
  - project_idinteger
  - positioninteger
  - task_countinteger
  - typestring
  - created_atstring
  - updated_atstring
- start_onstring
- due_onstring
- due_atstring
- done_atstring
- created_atstring
- updated_atstring

Example response

json

{
  "task": {
    "id": 0,
    "subject": "string",
    "description": "string",
    "author_id": 0,
    "assignee_ids": [
      0
    ],
    "estimate_hours": 0,
    "follower_ids": [
      0
    ],
    "mention_ids": [
      0
    ],
    "label_ids": [
      0
    ],
    "position": 0,
    "list_id": 0,
    "done": false,
    "status": "string",
    "list": {
      "id": 0,
      "name": "string",
      "project_id": 0,
      "position": 0,
      "task_count": 0,
      "type": "string",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    "start_on": "2024-01-15",
    "due_on": "2024-01-15",
    "due_at": "2024-01-15T10:30:00Z",
    "done_at": "2024-01-15T10:30:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

400Invalid parameters

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

401Unauthorized

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

403API access is only for organizations on an active plan

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

404Could not find record

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

429Rate limit exceeded

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

List project tasks

GET/v1/projects/{project_id}/tasks

Returns a collection of tasks for the given project.

Results can be filtered by assignee (all/assigned/unassigned) and updated[start]/updated[stop] time range.

Parameters

Name	In	Type	Description
page_start_id	query	integer (int32)	The page start ID.
page_limit	query	integer (int32)	The default page size
assignee	query	string	Whether to only include assigned tasks Possible values`allunassignedassigned`
updated[after]	query	string (date-time)	Start time (ISO 8601, Exclusive)
updated[start]	query	string (date-time)	Start time (ISO 8601)
updated[stop]	query	string (date-time)	Stop time (ISO 8601, Exclusive)
removed	query	boolean
project_idrequired	path	integer (int32)	A project ID

Responses

200A list of tasks

object

tasksarray
array<object>
items
object
task model
- idinteger
- subjectstring
- descriptionstring
- author_idinteger
- assignee_idsarray
  array<integer>
  items
  integer(int32)
- estimate_hoursnumber
- follower_idsarray
  array<integer>
  items
  integer(int32)
- mention_idsarray
  array<integer>
  items
  integer(int32)
- label_idsarray
  array<integer>
  items
  integer(int32)
- positioninteger
- list_idinteger
- doneboolean
- statusstring
- listobject
  object
  list model
  idinteger
  namestring
  project_idinteger
  positioninteger
  task_countinteger
  typestring
  created_atstring
  updated_atstring
- start_onstring
- due_onstring
- due_atstring
- done_atstring
- created_atstring
- updated_atstring

Example response

json

{
  "tasks": [
    {
      "id": 0,
      "subject": "string",
      "description": "string",
      "author_id": 0,
      "assignee_ids": [
        0
      ],
      "estimate_hours": 0,
      "follower_ids": [
        0
      ],
      "mention_ids": [
        0
      ],
      "label_ids": [
        0
      ],
      "position": 0,
      "list_id": 0,
      "done": false,
      "status": "string",
      "list": {
        "id": 0,
        "name": "string",
        "project_id": 0,
        "position": 0,
        "task_count": 0,
        "type": "string",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      },
      "start_on": "2024-01-15",
      "due_on": "2024-01-15",
      "due_at": "2024-01-15T10:30:00Z",
      "done_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}

400Invalid parameters

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

401Unauthorized

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

403API access is only for organizations on an active plan

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

404Could not find record

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

429Rate limit exceeded

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

List my assigned tasks

GET/v1/tasks/my/assigned

Returns a collection of tasks assigned to the current user.

Use removed=true to include removed tasks.

Parameters

Name	In	Type	Description
page_start_id	query	integer (int32)	The page start ID.
page_limit	query	integer (int32)	The default page size
removed	query	boolean

Responses

200A list of tasks

object

tasksarray
array<object>
items
object
task model
- idinteger
- subjectstring
- descriptionstring
- author_idinteger
- assignee_idsarray
  array<integer>
  items
  integer(int32)
- estimate_hoursnumber
- follower_idsarray
  array<integer>
  items
  integer(int32)
- mention_idsarray
  array<integer>
  items
  integer(int32)
- label_idsarray
  array<integer>
  items
  integer(int32)
- positioninteger
- list_idinteger
- doneboolean
- statusstring
- listobject
  object
  list model
  idinteger
  namestring
  project_idinteger
  positioninteger
  task_countinteger
  typestring
  created_atstring
  updated_atstring
- start_onstring
- due_onstring
- due_atstring
- done_atstring
- created_atstring
- updated_atstring

Example response

json

{
  "tasks": [
    {
      "id": 0,
      "subject": "string",
      "description": "string",
      "author_id": 0,
      "assignee_ids": [
        0
      ],
      "estimate_hours": 0,
      "follower_ids": [
        0
      ],
      "mention_ids": [
        0
      ],
      "label_ids": [
        0
      ],
      "position": 0,
      "list_id": 0,
      "done": false,
      "status": "string",
      "list": {
        "id": 0,
        "name": "string",
        "project_id": 0,
        "position": 0,
        "task_count": 0,
        "type": "string",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      },
      "start_on": "2024-01-15",
      "due_on": "2024-01-15",
      "due_at": "2024-01-15T10:30:00Z",
      "done_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}

400Invalid parameters

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

401Unauthorized

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

403API access is only for organizations on an active plan

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

404Could not find record

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

429Rate limit exceeded

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

Get task

GET/v1/tasks/{task_id}

Returns the task with the given ID.

Parameters

Name	In	Type	Description
task_idrequired	path	integer (int32)	A task ID

Responses

200A task

object

taskobject
object
task model
- idinteger
- subjectstring
- descriptionstring
- author_idinteger
- assignee_idsarray
  array<integer>
  items
  integer(int32)
- estimate_hoursnumber
- follower_idsarray
  array<integer>
  items
  integer(int32)
- mention_idsarray
  array<integer>
  items
  integer(int32)
- label_idsarray
  array<integer>
  items
  integer(int32)
- positioninteger
- list_idinteger
- doneboolean
- statusstring
- listobject
  object
  list model
  - idinteger
  - namestring
  - project_idinteger
  - positioninteger
  - task_countinteger
  - typestring
  - created_atstring
  - updated_atstring
- start_onstring
- due_onstring
- due_atstring
- done_atstring
- created_atstring
- updated_atstring

Example response

json

{
  "task": {
    "id": 0,
    "subject": "string",
    "description": "string",
    "author_id": 0,
    "assignee_ids": [
      0
    ],
    "estimate_hours": 0,
    "follower_ids": [
      0
    ],
    "mention_ids": [
      0
    ],
    "label_ids": [
      0
    ],
    "position": 0,
    "list_id": 0,
    "done": false,
    "status": "string",
    "list": {
      "id": 0,
      "name": "string",
      "project_id": 0,
      "position": 0,
      "task_count": 0,
      "type": "string",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    "start_on": "2024-01-15",
    "due_on": "2024-01-15",
    "due_at": "2024-01-15T10:30:00Z",
    "done_at": "2024-01-15T10:30:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

400Invalid parameters

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

401Unauthorized

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

403API access is only for organizations on an active plan

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

404Could not find record

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

429Rate limit exceeded

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

Update task

PATCH/v1/tasks/{task_id}

Updates a task.

Returns the updated task.

Only pass in the fields you want to change.

Parameters

Name	In	Type	Description
task_idrequired	path	integer (int32)	A task ID

Request body

object

task[subject]string
task[description]string
task[due_at]string
task[due_on]string
task[estimate_hours]number
task[assignee_ids]array
array
task[label_ids]array
array
task[external_id]integer

Responses

200A task

object

taskobject
object
task model
- idinteger
- subjectstring
- descriptionstring
- author_idinteger
- assignee_idsarray
  array<integer>
  items
  integer(int32)
- estimate_hoursnumber
- follower_idsarray
  array<integer>
  items
  integer(int32)
- mention_idsarray
  array<integer>
  items
  integer(int32)
- label_idsarray
  array<integer>
  items
  integer(int32)
- positioninteger
- list_idinteger
- doneboolean
- statusstring
- listobject
  object
  list model
  - idinteger
  - namestring
  - project_idinteger
  - positioninteger
  - task_countinteger
  - typestring
  - created_atstring
  - updated_atstring
- start_onstring
- due_onstring
- due_atstring
- done_atstring
- created_atstring
- updated_atstring

Example response

json

{
  "task": {
    "id": 0,
    "subject": "string",
    "description": "string",
    "author_id": 0,
    "assignee_ids": [
      0
    ],
    "estimate_hours": 0,
    "follower_ids": [
      0
    ],
    "mention_ids": [
      0
    ],
    "label_ids": [
      0
    ],
    "position": 0,
    "list_id": 0,
    "done": false,
    "status": "string",
    "list": {
      "id": 0,
      "name": "string",
      "project_id": 0,
      "position": 0,
      "task_count": 0,
      "type": "string",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    "start_on": "2024-01-15",
    "due_on": "2024-01-15",
    "due_at": "2024-01-15T10:30:00Z",
    "done_at": "2024-01-15T10:30:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

400Invalid parameters

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

401Unauthorized

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

403API access is only for organizations on an active plan

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

404Could not find record

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

429Rate limit exceeded

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

Complete task

PATCH/v1/tasks/{task_id}/complete

Marks a task as complete by moving it to the Done list.

Returns the completed task.

Parameters

Name	In	Type	Description
task_idrequired	path	integer (int32)	A task ID

Responses

200A task

object

taskobject
object
task model
- idinteger
- subjectstring
- descriptionstring
- author_idinteger
- assignee_idsarray
  array<integer>
  items
  integer(int32)
- estimate_hoursnumber
- follower_idsarray
  array<integer>
  items
  integer(int32)
- mention_idsarray
  array<integer>
  items
  integer(int32)
- label_idsarray
  array<integer>
  items
  integer(int32)
- positioninteger
- list_idinteger
- doneboolean
- statusstring
- listobject
  object
  list model
  - idinteger
  - namestring
  - project_idinteger
  - positioninteger
  - task_countinteger
  - typestring
  - created_atstring
  - updated_atstring
- start_onstring
- due_onstring
- due_atstring
- done_atstring
- created_atstring
- updated_atstring

Example response

json

{
  "task": {
    "id": 0,
    "subject": "string",
    "description": "string",
    "author_id": 0,
    "assignee_ids": [
      0
    ],
    "estimate_hours": 0,
    "follower_ids": [
      0
    ],
    "mention_ids": [
      0
    ],
    "label_ids": [
      0
    ],
    "position": 0,
    "list_id": 0,
    "done": false,
    "status": "string",
    "list": {
      "id": 0,
      "name": "string",
      "project_id": 0,
      "position": 0,
      "task_count": 0,
      "type": "string",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    "start_on": "2024-01-15",
    "due_on": "2024-01-15",
    "due_at": "2024-01-15T10:30:00Z",
    "done_at": "2024-01-15T10:30:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

400Invalid parameters

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

401Unauthorized

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

403API access is only for organizations on an active plan

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

404Could not find record

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}

429Rate limit exceeded

object

HubstaffTasks_Public_V1_Entities_Error model

codestring
Error code
errorstring
Descriptive error message

Example response

json

{
  "code": "string",
  "error": "string"
}