Tasks

The task is the basic object around which many operations in Asana are centered. In the Asana application, multiple tasks populate the middle pane according to some view parameters, and the set of selected tasks determines the more detailed information presented in the details pane.

A section, at its core, is a task whose name ends with the colon character :. Sections are unique in that they will be included in the memberships field of task objects returned in the API when the task is within a section. As explained below they can also be used to manipulate the ordering of a task within a project.

Queries return a compact representation of each object which is typically the id and name fields. Interested in a specific set of fields or all of the fields? Use field selectors to manipulate what data is included in a response.

Tasks have the following fields:

Field Description
id 1234 Read-only. Globally unique ID of the task.
assignee { id: 12345, name: 'Tim Bizarro' } null User to which this task is assigned, or null if the task is unassigned.
assignee_status 'upcoming' Scheduling status of this task for the user it is assigned to. This field can only be set if the assignee is non-null.
created_at '2012-02-22T02:06:58.147Z' Read-only. The time at which this task was created.
completed false True if the task is currently marked complete, false if not.
completed_at '2012-02-22T02:06:58.147Z' Read-only. The time at which this task was completed, or null if the task is incomplete.
custom_fields [ { id: 1646, name: 'Priority', type: 'enum', enum_value: { id: 126, name: 'P1' } }, ...] Array of custom fields applied to the task. These custom fields represent the values recorded on this task for a particular custom field. For example, these fields will contain an enum_value property for custom fields of type enum, a string_value property for custom fields of type string, and so on. Please note that the id returned on each custom field value is identical to the id of the custom field, which allows referencing the custom field metadata through the /custom_fields/custom_field-id endpoint.
due_on '2012-03-26' Date on which this task is due, or null if the task has no due date. This takes a date with YYYY-MM-DD format and should not be used together with due_at.
due_at '2012-02-22T02:06:58.147Z' Date and time on which this task is due, or null if the task has no due time. This takes a UTC timestamp and should not be used together with due_on.
external { id: 'my_id', data: 'A blob of information.' } Oauth Required. The external field allows you to store app-specific metadata on tasks, including an id that can be used to retrieve tasks and a data blob that can store app-specific character strings. Note that you will need to authenticate with Oauth to access or modify this data. Once an external id is set, you can use the notation external:custom_id to reference your object anywhere in the API where you may use the original object id. See the page on Custom External Data for more details.
followers [ { id: 1123, name: 'Mittens' }, ... ] Array of users following this task.
hearted false True if the task is hearted by the authorized user, false if not.
hearts [ { id: 1123, name: 'Mittens' }, ... ] Read-only. Array of users who have hearted this task.
modified_at '2012-02-22T02:06:58.147Z' Read-only. The time at which this task was last modified.

Note: This does not currently reflect any changes in associations such as projects or comments that may have been added or removed from the task.
name 'Buy catnip' Name of the task. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.
notes 'Mittens really likes the stuff from Humboldt.' More detailed, free-form textual information associated with the task.
num_hearts 5 Read-only. The number of users who have hearted this task.
projects [ { id: 1331, name: 'Stuff to Buy' }, ... ] Create-only. Array of projects this task is associated with. At task creation time, this array can be used to add the task to many projects at once. After task creation, these associations can be modified using the addProject and removeProject endpoints.
parent { id: 1234, name: 'Bug task' } Read-only. The parent of this task, or null if this is not a subtask. This property cannot be modified using a PUT request but you can change it with the setParent endpoint. You can create subtasks by using the subtasks endpoint.
workspace { id: 14916, name: 'My Workspace' } Create-only. The workspace this task is associated with. Once created, task cannot be moved to a different workspace. This attribute can only be specified at creation time.
memberships [ { project: { id: 1331, name: 'Bugs' }, section: { id: 1123, name: 'P1:' } }, ... ] Create-only. Array of projects this task is associated with and the section it is in. At task creation time, this array can be used to add the task to specific sections. After task creation, these associations can be modified using the addProject and removeProject endpoints. Note that over time, more types of memberships may be added to this property.
tags [ { id: 59746, name: 'Grade A' }, ... ] Create-only. Array of tags associated with this task. This property may be specified on creation using just an array of tag IDs. In order to change tags on an existing task use addTag and removeTag.

CREATE A TASK

POST    /tasks

Creating a new task is as easy as POSTing to the /tasks endpoint with a data block containing the fields you’d like to set on the task. Any unspecified fields will take on default values.

Every task is required to be created in a specific workspace, and this workspace cannot be changed once set. The workspace need not be set explicitly if you specify projects or a parent task instead.

projects can be a comma separated list of projects, or just a single project the task should belong to.

Parameter Description
workspace 1331 The workspace to create a task in.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks \
--data-urlencode "assignee=1235" \
--data-urlencode "notes=How are you today?" \
--data-urlencode "followers[0]=5678" \
--data-urlencode "name=Hello, world!" \
--data-urlencode "workspace=14916"

# Response
HTTP/1.1 201
{
  "data": {
    "created_at": "2012-02-22T02:06:58.158Z",
    "name": "Hello, world!",
    "parent": null,
    "completed_at": null,
    "notes": "How are you today?",
    "modified_at": "2012-02-22T02:06:58.158Z",
    "assignee_status": "inbox",
    "assignee": {
      "id": 1235,
      "name": "Tim Bizarro"
    },
    "completed": false,
    "followers": [
      {
        "id": 5678,
        "name": "Greg Sanchez"
      }
    ],
    "workspace": {
      "id": 14916,
      "name": "My Favorite Workspace"
    },
    "due_on": null,
    "id": 1001,
    "projects": [
      {
        "id": 14641,
        "name": "Cat Stuff"
      }
    ]
  }
}

POST    /workspaces/workspace-id/tasks

Creating a new task is as easy as POSTing to the /tasks endpoint with a data block containing the fields you’d like to set on the task. Any unspecified fields will take on default values.

Every task is required to be created in a specific workspace, and this workspace cannot be changed once set. The workspace need not be set explicitly if you specify a project or a parent task instead.

Parameter Description
workspace 1331 Required: The workspace to create a task in.

GET A TASK

GET    /tasks/task-id

Returns the complete task record for a single task.

Parameter Description
task 124816 Required: The task to get.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001

# Response
HTTP/1.1 200
{
  "data": {
    "assignee": {
      "id": 1234,
      "name": "Tim Bizarro"
    },
    "created_at": "2012-02-22T02:06:58.158Z",
    "...": "..."
  }
}

UPDATE A TASK

PUT    /tasks/task-id

A specific, existing task can be updated by making a PUT request on the URL for that task. Only the fields provided in the data block will be updated; any unspecified fields will remain unchanged.

When using this method, it is best to specify only those fields you wish to change, or else you may overwrite changes made by another user since you last retrieved the task.

Returns the complete updated task record.

Parameter Description
task 124816 Required: The task to update.
# Request
curl --request PUT -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001 \
--data-urlencode "assignee=me"

# Response
HTTP/1.1 200
{
  "data": {
    "assignee": {
      "id": 1234,
      "name": "Tim Bizarro"
    },
    "id": 1001,
    "...": "..."
  }
}

DELETE A TASK

DELETE    /tasks/task-id

A specific, existing task can be deleted by making a DELETE request on the URL for that task. Deleted tasks go into the “trash” of the user making the delete request. Tasks can be recovered from the trash within a period of 30 days; afterward they are completely removed from the system.

Returns an empty data record.

Parameter Description
task 124816 Required: The task to delete.
# Request
curl --request DELETE -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001

# Response
HTTP/1.1 200
{
  "data": {}
}

QUERY FOR TASKS

GET    /projects/projectId-id/tasks

Returns the compact task records for all tasks within the given project, ordered by their priority within the project.

Parameter Description
projectId 13579 Required: The project in which to search for tasks.

GET    /tags/tag-id/tasks

Returns the compact task records for all tasks with the given tag.

Parameter Description
tag 11235 Required: The tag in which to search for tasks.

GET    /sections/section-id/tasks

Board view only: Returns the compact section records for all tasks within the given section.

Parameter Description
section 97531 Required: The section in which to search for tasks.

GET    /tasks

Returns the compact task records for some filtered set of tasks. Use one or more of the parameters provided to filter the tasks returned. You must specify a project or tag if you do not specify assignee and workspace.

Parameter Description
assignee 14641 me sashimi@asana.com The assignee to filter tasks on.

Note: If you specify assignee, you must also specify the workspace to filter on.
project 13579 The project to filter tasks on.
section 97531 The section to filter tasks on.

Note: Currently, this is only supported in board views.
workspace 1331 The workspace or organization to filter tasks on.

Note: If you specify workspace, you must also specify the assignee to filter on.
completed_since '2012-02-22T02:06:58.158Z' now Only return tasks that are either incomplete or that have been completed since this time.
modified_since '2012-02-22T02:06:58.158Z' now Only return tasks that have been modified since the given time.

Note: A task is considered “modified” if any of its properties change, or associations between it and other objects are modified (e.g. a task being added to a project). A task is not considered modified just because another object it is associated with (e.g. a subtask) is modified. Actions that count as modifying the task include assigning, renaming, completing, and adding stories.

Show a task.

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001

# Response
HTTP/1.1 200
{
  "data": {
    "assignee": {
      "id": 1234,
      "name": "Tim Bizarro"
    },
    "created_at": "2012-02-22T02:06:58.158Z",
    "...": "..."
  }
}

Show tasks assigned to me in a workspace or organization.

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks?workspace=14916&assignee=me

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 1248,
      "name": "Buy catnip"
    },
    {
      "id": 24816,
      "name": "Reflect on role of kittens in society"
    },
    {
      "null": "..."
    }
  ]
}

CUSTOM FIELD VALUES

Custom fields define user-specific information that can be used to configure tasks within a project to track information that is specific to one particular project. Be sure to reference the Custom Fields guide to get an understanding for the concepts of custom fields and how they relate to resources within Asana.

When a custom field is associated with a project, tasks in that project can carry additional custom field values which represent the value of the field on that particular task - for instance, the selected item from an enum type custom field. These custom fields will appear as an array in a custom_fields property of the task, along with some basic information which can be used to associate the custom field value with the custom field metadata.

Custom field value for an enum field

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001

# Response
HTTP/1.1 200
{
  "data": {
    "id": 1001,
    "name": "Hello, world!",
    "completed": false,
    "...": "...",
    "custom_fields": [
      {
        "id": 124578,
        "name": "Priority",
        "type": "enum",
        "enum_value": {
          "id": 789,
          "name": "Low",
          "enabled": true,
          "color": "blue"
        }
      },
      "~..."
    ]
  }
}

Custom field value for a text field

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001

# Response
HTTP/1.1 200
{
  "data": {
    "id": 1001,
    "name": "Hello, world!",
    "completed": false,
    "...": "...",
    "custom_fields": [
      {
        "id": 134679,
        "name": "Owner",
        "type": "text",
        "text_value": "Greg Sanchez"
      },
      "~..."
    ]
  }
}

Custom field value for a number field

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001

# Response
HTTP/1.1 200
{
  "data": {
    "id": 1001,
    "name": "Hello, world!",
    "completed": false,
    "...": "...",
    "custom_fields": [
      {
        "id": 134679,
        "name": "Price",
        "type": "number",
        "number_value": "1.56"
      },
      "~..."
    ]
  }
}

CUSTOM FIELD VALUE-SPECIFIC DATA

Custom fields will return differing properties based on the custom field’s type.

Custom fields of type text will return a text_value property containing the string of text for the field. Custom fields of type number will return a number_value property containing the number for the field. Custom fields of type enum will return an enum_value property containing an object that represents the selection of the enum value.

enum_value warrants special consideration: it represents a single entry from the enum_options array in the custom field metadata. It has these properties:

id: the id of the selected entry. name: the display name of the selected entry. enabled: whether the selection is modifiable. (See the documentation on disabled values for more information).

SETTING CUSTOM FIELD VALUES

Custom fields are set with PUT requests similarly to setting other fields on tasks; the format of the request is to set the id to the new value. That is, custom_fields:{custom_field_id:custom_field_value}

Custom fields of type text are set by passing in custom_field_id:string Custom fields of type number are set by passing in custom_field_id:number Custom fields of type enum are set by passing in custom_field_id:enum_value_id

WORK WITH SUBTASKS

Creating a subtask is the same as a creating an normal task, but instead of specifying a workspace you must specify a parent task. Each task can only have a single parent and you can use the setParent endpoint to add or remove a parent from an existing task.

Created subtasks are added to the beginning of their parent’s list of subtasks.

You can find all of the subtasks of a task via the tasks/:ID/subtasks endpoint.

GET    /tasks/task-id/subtasks

Returns a compact representation of all of the subtasks of a task.

Parameter Description
task 124816 Required: The task to get the subtasks of.

POST    /tasks/task-id/subtasks

Creates a new subtask and adds it to the parent task. Returns the full record for the newly created subtask.

Parameter Description
task 124816 Required: The task to add a subtask to.

POST    /tasks/task-id/setParent

Changes the parent of a task. Each task may only be a subtask of a single parent, or no parent task at all. Returns an empty data block.

Parameter Description
task 124816 Required: The task to change the parent of.
parent 124816 Required: The new parent of the task, or null for no parent.

TASK ACTIVITY AND COMMENTS

Tasks, like some other objects in the system, have a series of stories associated with them. A story can be an indicator of some action taken on a task (such as completing it), or it could be a comment left by a user.

See the sections on querying for all stories and commenting on an object for more information.

GET    /tasks/task-id/stories

Returns a compact representation of all of the stories on the task.

Parameter Description
task 124816 Required: The task containing the stories to get.

POST    /tasks/task-id/stories

Adds a comment to a task. The comment will be authored by the currently authenticated user, and timestamped when the server receives the request.

Returns the full record for the new story added to the task.

Parameter Description
task 124816 Required: Globally unique identifier for the task.
text 'This is a comment.' Required: The plain text of the comment to add.

TASK, PROJECT, AND SECTION ASSOCIATIONS

Each task can be associated with zero or more projects.

The projects endpoint on a task will return a compact representation of each of the projects on the task specified.

The addProject or removeProject endpoints can be used to add and remove projects that a task is a member of by providing the required project parameter.

Note that a task may belong to many projects and a single section within each project.

Requests to add/remove projects, if successful, will return success and an empty data block.

GET    /tasks/task-id/projects

Returns a compact representation of all of the projects the task is in.

Parameter Description
task 124816 Required: The task to get projects on.

POST    /tasks/task-id/addProject

Adds the task to the specified project, in the optional location specified. If no location arguments are given, the task will be added to the end of the project.

addProject can also be used to reorder a task within a project or section that already contains it.

At most one of insert_before, insert_after, or section should be specified. Inserting into a section in an non-order-dependent way can be done by specifying section, otherwise, to insert within a section in a particular place, specify insert_before or insert_after and a task within the section to anchor the position of this task.

Returns an empty data block.

Parameter Description
task 124816 Required: The task to add to a project.
project 13579 Required: The project to add the task to.
insert_after 124816 null A task in the project to insert the task after, or null to insert at the beginning of the list.
insert_before 124816 null A task in the project to insert the task before, or null to insert at the end of the list.
section 124816 A section in the project to insert the task into. The task will be inserted at the bottom of the section.

POST    /tasks/task-id/removeProject

Removes the task from the specified project. The task will still exist in the system, but it will not be in the project anymore.

Returns an empty data block.

Parameter Description
task 124816 Required: The task to remove from a project.
project 13579 Required: The project to remove the task from.

TAGS ON TASKS

Each task can be associated with zero or more tags in the system. The API allows you to query and change those associations.

You can get the list of tags associated with a task by using the tags endpoint on a task, which will return a compact representation of each of the tags on the task specified.

You can add or remove a tag using the addTag or removeTag endpoints, respectively, providing the parameters below.

Requests to add/remove tags, if successful, will return success and an empty data block.

GET    /tasks/task-id/tags

Returns a compact representation of all of the tags the task has.

Parameter Description
task 124816 Required: The task to get tags on.

POST    /tasks/task-id/addTag

Adds a tag to a task. Returns an empty data block.

Parameter Description
task 124816 Required: The task to add a tag to.
tag 11235 Required: The tag to add to the task.

POST    /tasks/task-id/removeTag

Removes a tag from the task. Returns an empty data block.

Parameter Description
task 124816 Required: The task to remove a tag from.
tag 11235 Required: The tag to remove from the task.

FOLLOWERS ON TASKS

Each task can be associated with zero or more followers in the system.

You can add or remove followers using the addFollowers or removeFollowers endpoints, respectively, providing the parameters below.

Requests to add/remove followers, if successful, will return the complete updated task record, described above.

POST    /tasks/task-id/addFollowers

Adds each of the specified followers to the task, if they are not already following. Returns the complete, updated record for the affected task.

Parameter Description
task 124816 Required: The task to add followers to.
followers [133713, 184253] Required: An array of followers to add to the task.

POST    /tasks/task-id/removeFollowers

Removes each of the specified followers from the task if they are following. Returns the complete, updated record for the affected task.

Parameter Description
task 124816 Required: The task to remove followers from.
followers [133713, 184253] Required: An array of followers to remove from the task.