The commands listed in this chapter allow you to manage Tasks via the API.

About Tasks #

The following Task fields are available:

• name (string) - The Task name is a required field when creating a Task.
• body (text) - The Task description.
• visibility (integer) - Object visibility. 0 is private and 1 is the value of normal visibility.
• category_id (integer) - Object category.
• label_id (integer) - Object label.
• milestone_id (integer) - ID of the parent Milestone.
• priority (integer) - The priority can have one of five integer values, ranging from -2 (lowest) to 2 (highest). 0 marks normal.
• assignee_id (integer) - The user assigned and responsible for the Task.
• other_assignees (array) - The people assigned to the Task.
• due_on (date) - The task due date.
• created_by_id (integer) - Use for a known user who already has an account in the system.
• created_by_name (string) - Use for anonymous user, who don't have an account in the system (can not be used with created_by_id).
• created_by_email (string) - Used for anonymous users.

Here is a list of additional resources used by Tasks:

• Categories
• Attachments
• Comments
• Reminders

Additional commands are available in the following articles:

• Subscription Related Commands
• Completion Status Related Commands
• Object State Related Commands
• Project Object Operations Commands

projects/:project_id/tasks #

This command lists all open and completed non-archived Tasks from a Project.

Method: GET

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<tasks>
  <task>
    <id>12</id>
    <name>
      <![CDATA[Task example]]>
    </name>
     ...
  </task>
  <task>
    <id>13</id>
    <name>
      <![CDATA[Some task]]>
    </name>
     ...
  </task>
</tasks>

projects/:project_id/tasks/archive #

This command displays all archived tasks from a project.

Method: GET

Example response:

1
2
3
4
5
6
7
8
9

<tasks>
  <task>
    <id>12</id>
    <name>
      <![CDATA[Task example]]>
    </name>
     ...
  </task>
</task>

projects/:project_id/tasks/add #

This command creates a new Task in the selected project.

Method: POST

Request example:

1
2

task[name]=New Task
submitted=submitted

Response:

1
2
3
4
5
6
7

<task>
  <id>14</id>
  <name>
    <![CDATA[New Task]]>
  </name>
   ...
</task>

projects/:project_id/tasks/:task_id #

This command displays the Task details.

Method: GET

Response:

1
2
3
4
5
6
7

<task>
  <id>14</id>
  <name>
    <![CDATA[api task example]]>
  </name>
   ...
</task>

projects/:project_id/tasks/:task_id/edit #

This command updates the properties of an existing Task.

Method: POST

Reqest example:

1
2

task[name]=Updated Task Name
submitted=submitted

Response:

1
2
3
4
5
6
7

<task>
  <id>14</id>
  <name>
    <![CDATA[Updated Task Name]]>
  </name>
    ...
</task>

projects/:project_id/tasks/:task_id/attachments/add #

This command will add attachment to one of your Tasks.

Method: POST

Request example:

1
2
3
4

task[name]=New Task with Attachment
enctype=multipart/form-data
input type=file
submitted=submitted

About Subtasks #

Subtasks can be added to a Task to provide a detailed rundown of what needs to be done. All subtask related commands are carried out in the context of the parent Task.

This is the list of available subtask fields:

• body (text) - The Subtask name is required field when creating a new Subtask.
• assignee (integer) - The person assigned to the object.
• priority (integer) - Priority can have five integer values ranging from -2 (lowest) to 2 (highest). 0 is normal priority.
• label_id (date) - Label ID of the Subtask.
• due_on (date) - Date when the subtask is due.

Additional commands can be found in the following articles:

• Subscription Related Commands
• Completion Status Related Commands
• Object State Related Commands

projects/:project_id/tasks/:task_id/subtasks #

This command displays all Subtasks for a given Task in a specific project.

Method: GET

Example response:

1
2
3
4
5
6
7
8
9
10

<subtasks>
  <subtask>
    <id>1</id>
    <name>
      <![CDATA[first subtask]]>
    </name>
     ...
  </subtask>
  ...
</subtasks>

projects/:project_id/tasks/:task_id/subtasks/add #

This command creates a new Subtask for the specified project in a Task.

Method: POST

Request example:

1
2

subtask[body]=Subtask made with API
submitted=submitted

Response:

1
2
3
4
5
6
7

<subtask>
  <id>3</id>
  <body>
    <![CDATA[subtask made with api]]>
  </body>
  ...
</subtask>

projects/:project_id/tasks/:task_id/subtasks/:subtask_id #

This command displays Subtask details.

Method: GET

Response:

1
2
3
4
5
6
7

<subtask>
  <id>2</id>
  <name>
    <![CDATA[second subtask]]>
  </name>
  ...
</subtask>

/projects/:project_id/tasks/:task_id/subtasks/:subtasks_id/edit #

This command updates existing Subtask details.

Method: POST

Request example:

1
2
3

subtask[body]=Subtask updated with API
subtask[due_on]=2014-07-25
submitted=submitted

Response:

1
2
3
4
5
6
7
8
9
10

<subtask>
  <id>3</id>
  <due_on>
    <![CDATA[2012-07-25]]>
  </due_on>
  <body>
    <![CDATA[Subtask updated with API]]>
  </body>
  ...
</subtask>