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.
dependencies [ { id: 1234 }, ... ] Read-only. Array of resources referencing tasks that this task depends on. The objects contain only the ID of the dependency.
dependents [ { id: 1234 }, ... ] Read-only. Array of resources referencing tasks that depend on this task. The objects contain only the ID of the dependent.
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.
liked false True if the task is liked by the authorized user, false if not.
likes [ { id: 1123, name: 'Mittens' }, ... ] Read-only. Array of users who have liked 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.
html_notes '<body>Mittens <em>really</em> likes the stuff from Humboldt.</body>' The notes of the text with formatting as HTML.

Note: This field is under active migration—please see our blog post for more information.
num_likes 5 Read-only. The number of users who have liked 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.
start_on '2012-03-26' Date on which this task is due, or null if the task has no start date. This field takes a date with YYYY-MM-DD format.

Note: due_on or due_at must be present in the request when setting or unsetting the start_on parameter.
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.

Create a task.

# 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"
      }
    ]
  }
}

Create a subtask.

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/2272/subtasks \
--data-urlencode "assignee=1235" \
--data-urlencode "notes=He's going to be upset." \
--data-urlencode "followers[0]=5678" \
--data-urlencode "name=Tell Luke"

# Response
HTTP/1.1 201
{
  "data": {
    "created_at": "2012-02-22T02:06:58.158Z",
    "name": "Tell Luke",
    "parent": {
      "id": 2272,
      "name": "Tell kids I am their father."
    },
    "completed_at": null,
    "notes": "He's going to be upset.",
    "modified_at": "2012-02-22T02:06:58.158Z",
    "assignee_status": "inbox",
    "assignee": {
      "id": 1235,
      "name": "Darth Vader"
    },
    "completed": false,
    "followers": [
      {
        "id": 5678,
        "name": "Emperor Palpatine"
      }
    ],
    "workspace": {
      "id": 14916,
      "name": "Star Wars"
    },
    "due_on": null,
    "id": 1001,
    "projects": []
  }
}

Set the parent for an existing task.

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/2272/setParent \
--data-urlencode "parent=1331"

# Response
HTTP/1.1 200
{
  "data": {
    "...": "...",
    "id": 2272,
    "parent": [
      {
        "id": 1331,
        "name": "Tell kids I am their father"
      }
    ],
    "name": "Tell Luke"
  }
}

Add project to a task.

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001/addProject \
--data-urlencode "project=14641"

# Response

{
  "data": {}
}

Remove project from a task.

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001/removeProject \
--data-urlencode "project=14641"

# Response

{
  "data": {}
}

Add tag to a task.

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001/addTag \
--data-urlencode "tag=1771"

# Response

{
  "data": {}
}

Remove tag from a task.

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001/removeTag \
--data-urlencode "tag=1771"

# Response

{
  "data": {}
}

Add followers to a task.

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001/addFollowers \
--data-urlencode "followers[0]=1235"

# Response
HTTP/1.1 200
{
  "data": {
    "followers": [
      {
        "id": 1235,
        "name": "Darth Vader"
      }
    ],
    "id": 1001,
    "...": "..."
  }
}

Remove followers from a task.

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001/removeFollowers \
--data-urlencode "followers[0]=1235"

# Response
HTTP/1.1 200
{
  "data": {
    "followers": [],
    "id": 1001,
    "...": "..."
  }
}
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.

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 all of a task’s subtasks.

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

# Response

{
  "data": [
    {
      "id": 5005,
      "name": "Steal Underwear"
    },
    {
      "id": 6709,
      "name": "???"
    },
    {
      "id": 9812,
      "name": "Profit"
    }
  ]
}

Show list of projects on a task.

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

# Response

{
  "data": [
    {
      "id": 1331,
      "name": "Things To Buy"
    },
    {
      "id": 14641,
      "name": "Cat Stuff"
    }
  ]
}

Show list of tags on a task.

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

# Response

{
  "data": [
    {
      "id": 1331,
      "name": "orange"
    },
    {
      "id": 1771,
      "name": "fluffy"
    }
  ]
}

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": "..."
    }
  ]
}

Show all of a task’s subtasks.

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

# Response

{
  "data": [
    {
      "id": 5005,
      "name": "Steal Underwear"
    },
    {
      "id": 6709,
      "name": "???"
    },
    {
      "id": 9812,
      "name": "Profit"
    }
  ]
}

Show list of projects on a task.

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

# Response

{
  "data": [
    {
      "id": 1331,
      "name": "Things To Buy"
    },
    {
      "id": 14641,
      "name": "Cat Stuff"
    }
  ]
}

Show list of tags on a task.

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

# Response

{
  "data": [
    {
      "id": 1331,
      "name": "orange"
    },
    {
      "id": 1771,
      "name": "fluffy"
    }
  ]
}

SEARCH FOR TASKS IN A WORKSPACE

GET    /workspaces/workspace-id/tasks/search

The search endpoint allows you to build complex queries to find and fetch exactly the data you need from Asana. For a more comprehensive description of all the query parameters and limitations of this endpoint, see our long-form documentation for this feature.

Parameter Description
workspace 1331 Required: The workspace or organization in which to search for tasks.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/workspaces/1337/tasks/search \
--data-urlencode "completed=false" \
--data-urlencode "text=dog" \
--data-urlencode "assignee.any=me,gsanchez@example.com" \
--data-urlencode "due_on.before=2018-07-15"

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 2001,
      "name": "Dog treats"
    },
    {
      "id": 2002,
      "name": "Dog bed"
    },
    "~..."
  ]
}

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/task-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.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/7331/subtasks

# Response

{
  "data": [
    {
      "id": 5005,
      "name": "Steal Underwear"
    },
    {
      "id": 6709,
      "name": "???"
    },
    {
      "id": 9812,
      "name": "Profit"
    }
  ]
}
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.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/2272/subtasks \
--data-urlencode "assignee=1235" \
--data-urlencode "notes=He's going to be upset." \
--data-urlencode "followers[0]=5678" \
--data-urlencode "name=Tell Luke"

# Response
HTTP/1.1 201
{
  "data": {
    "created_at": "2012-02-22T02:06:58.158Z",
    "name": "Tell Luke",
    "parent": {
      "id": 2272,
      "name": "Tell kids I am their father."
    },
    "completed_at": null,
    "notes": "He's going to be upset.",
    "modified_at": "2012-02-22T02:06:58.158Z",
    "assignee_status": "inbox",
    "assignee": {
      "id": 1235,
      "name": "Darth Vader"
    },
    "completed": false,
    "followers": [
      {
        "id": 5678,
        "name": "Emperor Palpatine"
      }
    ],
    "workspace": {
      "id": 14916,
      "name": "Star Wars"
    },
    "due_on": null,
    "id": 1001,
    "projects": []
  }
}
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. When using insert_before and insert_after, at most one of those two options can be specified, and they must already be subtasks of the parent.

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.
insert_after 124816 null A subtask of the parent to insert the task after, or null to insert at the beginning of the list.
insert_before 124816 null A subtask of the parent to insert the task before, or null to insert at the end of the list.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/2272/setParent \
--data-urlencode "parent=1331"

# Response
HTTP/1.1 200
{
  "data": {
    "...": "...",
    "id": 2272,
    "parent": [
      {
        "id": 1331,
        "name": "Tell kids I am their father"
      }
    ],
    "name": "Tell Luke"
  }
}

WORK WITH DEPENDENCIES You can mark that a task depends on another task by using the /tasks/task-id/addDependencies and /tasks/task-id/addDependents endpoints. These associations can be removed with the /tasks/task-id/removeDependencies and /tasks/task-id/removeDependents endpoints.

A task cannot depend on itself, and a task cannot depend on another task that already depends on it, e.g. task 1 cannot be made to depend on task 2 if task 2 already depends on task 1.

You can find all of the dependencies of a task via the /tasks/task-id/dependencies endpoint, and all of its dependents via the /tasks/task-id/dependents endpoint.

GET    /tasks/task-id/dependencies

Returns the compact representations of all of the dependencies of a task.

Parameter Description
task 124816 Required: The task to get dependencies on.
GET    /tasks/task-id/dependents

Returns the compact representations of all of the dependents of a task.

Parameter Description
task 124816 Required: The task to get dependents on.
POST    /tasks/task-id/addDependencies

Marks a set of tasks as dependencies of this task, if they are not already dependencies. A task can have at most 15 dependencies.

Parameter Description
task 124816 Required: The task to add dependencies to.
dependencies [133713, 184253] Required: An array of task IDs that this task should depend on.
POST    /tasks/task-id/addDependents

Marks a set of tasks as dependents of this task, if they are not already dependents. A task can have at most 30 dependents.

Parameter Description
task 124816 Required: The task to add dependents to.
dependents [133713, 184253] Required: An array of task IDs that should depend on this task.
POST    /tasks/task-id/removeDependencies

Unlinks a set of dependencies from this task.

Parameter Description
task 124816 Required: The task to remove dependencies from.
dependencies [133713, 184253] Required: An array of task IDs to remove as dependencies.
POST    /tasks/task-id/removeDependents

Unlinks a set of dependents from this task.

Parameter Description
task 124816 Required: The task to remove dependents from.
dependents [133713, 184253] Required: An array of task IDs to remove as dependents.

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.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001/projects

# Response

{
  "data": [
    {
      "id": 1331,
      "name": "Things To Buy"
    },
    {
      "id": 14641,
      "name": "Cat Stuff"
    }
  ]
}
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.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001/addProject \
--data-urlencode "project=14641"

# Response

{
  "data": {}
}
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.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001/removeProject \
--data-urlencode "project=14641"

# Response

{
  "data": {}
}

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.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001/tags

# Response

{
  "data": [
    {
      "id": 1331,
      "name": "orange"
    },
    {
      "id": 1771,
      "name": "fluffy"
    }
  ]
}
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.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001/addTag \
--data-urlencode "tag=1771"

# Response

{
  "data": {}
}
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.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001/removeTag \
--data-urlencode "tag=1771"

# Response

{
  "data": {}
}

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.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001/addFollowers \
--data-urlencode "followers[0]=1235"

# Response
HTTP/1.1 200
{
  "data": {
    "followers": [
      {
        "id": 1235,
        "name": "Darth Vader"
      }
    ],
    "id": 1001,
    "...": "..."
  }
}
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.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001/removeFollowers \
--data-urlencode "followers[0]=1235"

# Response
HTTP/1.1 200
{
  "data": {
    "followers": [],
    "id": 1001,
    "...": "..."
  }
}