Documentation (2024.2 Enterprise)

# Task

Tasks can be used to keep track of things that need to be done in a Project. They are grouped into Milestones.

- Attributes
- Searchable attributes
- Child objects
- Operations
  - `GET /projects/:project_id/tasks`
  - `GET /projects/:project_id/tasks/:id`
  - `POST /projects/:project_id/tasks`
  - `PUT /projects/:project_id/tasks/:id`
  - `DELETE /projects/:project_id/tasks/:id`
  - `GET /projects/:project_id/tasks/count`

## Attributes

Task object has support for storing custom attributes.

### id

Automatically generated URL-friendly identifier for the task.

- Type: `integer`
- Immutable: `true`
- Unique: `true` (in project scope)
- Required: `true`

### title

Human-readable title for the task.

- Type: `string`
- Required: `true`
- Minimum length: `1`
- Maximum length: `100`

### description

A free-form description of the task.

- Type: `string`
- Default: `""`
- Maximum length: `50000`

### due_date

Optional due date of the task.

- Type: `timestamp`

### state

State must be one of states defined in the milestone it belongs to.

- Type: `string`
- Required: `true`

### priority

Priority must be either one of the priorities defined in the milestone, or integer based when milestone does not define priorities.

- Type: `string` / `integer`
- Required: `true`

### labels

Tasks can have optional labels, which are defined in the project it belongs to.

- Type: `array`

### creator

Creator of the task can be expanded to get the full User or Collaborator object by including the query parameter `expand=creator` in the request.

- Type: `string` / `object`

### members

Project users assigned to the task. Can be expanded to get the full User and/or Collaborator objects by including the query parameter `expand=members` in the request. Please note that you can only assign users from the project the issue was created to.

- Type: `array`

### milestone

Milestone of the task can be expanded to get the full Milestone object by including the query parameter `expand=milestone` in the request.

- Type: `string` / `object`
- Required: `true`

## Searchable attributes

Tasks can be searched by their `id`, `title`, and `description` attributes. See the search documentation for instructions how to do this.

## Child objects

The following child objects can be attached to the tasks returned, to eliminate the need for requesting them separately:

Object | Attribute
--- | ---
Comment | `comments`
Attachment | `attachments`
Subscriber | `subscribers`

For example to get all the comments and attachments for the task, attach `include=comments,attachments` to your GET request.

See the child object API documentation for a description of the possible operations.

## Operations

### GET /projects/:project_id/tasks

Returns all the tasks in the project, with optional limit and offset parameters, as a metadata-results object.

### GET /projects/:project_id/tasks/:id

Returns specific task object.

#### Example Request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/projects/luotsi/tasks/1

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2014-05-13T07:48:47Z",
      "id": 1,
      "created_at": "2014-04-23T12:20:17Z",
      "updated_at": "2014-05-09T14:31:01Z",
      "title": "Feature request",
      "description": "This would be an awesome feature!",
      "due_date": "2014-05-20T12:00:00Z",
      "state": "open",
      "priority": 3,
      "labels": [
        "bug"
      ],
      "creator": {
        "id": "jp"
      },
      "members": [
        {
          "id": "tair"
        },
        {
          "id": "vellu"
        }
      ],
      "milestone": {
        "id": "default"
      },
      "properties": {

      }
    }

### POST /projects/:project_id/tasks

Creates a new task to the project. Returns the created task object.

#### Example Request

    curl -X POST \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "title": "Found a bug", "description": "Fix all the bugs!", "milestone": "current", "state": "next", "priority": "normal" }'
      https://helixteamhub.cloud/api/projects/luotsi/tasks

#### Example Response

    {
      "api_status": 201,
      "api_timestamp": "2014-05-13T07:55:26Z",
      "id": 2,
      "created_at": "2014-05-13T07:55:26Z",
      "updated_at": "2014-05-13T07:55:26Z",
      "title": "Found a bug",
      "description": "Fix all the bugs!",
      "due_date": null,
      "state": "next",
      "priority": "normal",
      "labels": [

      ],
      "creator": {
        "id": "jp"
      },
      "members": [

      ],
      "milestone": {
        "id": "current"
      },
      "properties": {

      }
    }

### PUT /projects/:project_id/tasks/:id

Updates a task. Returns the updated task object.

#### Example Request

    curl -X PUT \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "members": ["tair", "vellu"] }' \
      https://helixteamhub.cloud/api/projects/luotsi/tasks/2

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2014-05-13T07:58:00Z",
      "id": 2,
      "created_at": "2014-05-13T07:55:26Z",
      "updated_at": "2014-05-13T07:58:00Z",
      "title": "Found a bug",
      "description": "Fix all the bugs!",
      "due_date": null,
      "state": "next",
      "priority": "normal",
      "labels": [

      ],
      "creator": {
        "id": "jp"
      },
      "members": [
        {
          "id": "tair"
        },
        {
          "id": "vellu"
        }
      ],
      "milestone": {
        "id": "current"
      },
      "properties": {

      }
    }

### DELETE /projects/:project_id/tasks/:id

Deletes a task. Returns the deleted task object.

#### Example Request

    curl -X DELETE \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/projects/luotsi/tasks/2

### GET /projects/:project_id/tasks/count

Returns an object containing the total count of tasks in the project. Accepts optional query parameters for filtering the result set.

#### Example Request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/projects/luotsi/tasks/count?milestone=current

#### Example Response

    {
      "api_status": 200,
      "api_timestamp": "2014-05-15T13:45:54Z",
      "count": 142
    }

Your search for returned results

Your search for returned results