Projects

A project represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.

Projects in organizations are shared with a single team. You cannot currently change the team of a project via the API. Non-organization workspaces do not have teams and so you should not specify the team of project in a regular workspace.

Followers of a project are a subset of the members of that project. Followers of a project will receive all updates including tasks created, added and removed from that project. Members of the project have access to and will receive status updates of the project. Adding followers to a project will add them as members if they are not already, removing followers from a project will not affect membership.

Projects have the following fields:

Field Description
name 'Stuff to buy' Name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.
id 1234 Read-only. Globally unique ID of the project.
owner { id: 12345, name: 'Tim Bizarro' } null The current owner of the project, may be null.
current_status { 'color': green, 'text': 'All gravy!', 'author':{ ... } ... } A description of the project’s status containing a color (must be either null or one of: green, yellow, red) and a short description.
due_date '2012-03-26' The day on which this project is due. This takes a date with format YYYY-MM-DD.
created_at '2012-02-22T02:06:58.147Z' Read-only. The time at which this project was created.
modified_at '2012-02-22T02:06:58.147Z' Read-only. The time at which this project was last modified.

Note: This does not currently reflect any changes in associations such as tasks or comments that may have been added or removed from the project.
archived false True if the project is archived, false if not. Archived projects do not show in the UI by default and may be treated differently for queries.
public false True if the project is public to the organization. If false, do not share this project with other users in this organization without explicitly checking to see if they have access.
members [ { id: 1123, name: 'Mittens' }, ... ] Read-only. Array of users who are members of this project.
followers [ { id: 1123, name: 'Mittens' }, ... ] Read-only. Array of users following this project. Followers are a subset of members who receive all notifications for a project, the default notification setting when adding members to a project in-product.
custom_field_settings [ { id: 258147, custom_field: {id: 1646, name: 'Priority', type: 'enum'}, project: {id: 1331, name: 'Bugs'} }, ...] Read-only. Array of Custom Field Settings (in compact form).
color 'dark-purple' Color of the project. Must be either null or one of: dark-pink, dark-green, dark-blue, dark-red, dark-teal, dark-brown, dark-orange, dark-purple, dark-warm-gray, light-pink, light-green, light-blue, light-red, light-teal, light-yellow, light-orange, light-purple, light-warm-gray.
notes 'These are things we need to purchase.' More detailed, free-form textual information associated with the project.
workspace { id: 14916, name: 'My Workspace' } Create-only. The workspace or organization this project is associated with. Once created, projects cannot be moved to a different workspace. This attribute can only be specified at creation time.
team { id: 692353, name: 'organization.com Marketing' } Create-only. The team that this project is shared with. This field only exists for projects in organizations.
layout 'board' 'list' The layout (board or list view) of the project.

CREATE A PROJECT

POST    /projects

Creates a new project in a workspace or team.

Every project is required to be created in a specific workspace or organization, and this cannot be changed once set. Note that you can use the workspace parameter regardless of whether or not it is an organization.

If the workspace for your project is an organization, you must also supply a team to share the project with.

Returns the full record of the newly created project.

Parameter Description
workspace 1331 Required: The workspace or organization to create the project in.
team 14916 If creating in an organization, the specific team to create the project in.

Create a new project.

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/projects \
--data-urlencode "notes=These are things we want to purchase." \
--data-urlencode "name=Things to Buy" \
--data-urlencode "workspace=14916"

# Response
HTTP/1.1 201
{
  "data": {
    "notes": "These are things we want to purchase.",
    "null": "...",
    "id": 1331,
    "name": "Things to Buy"
  }
}

Add a custom field setting to a project

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/projects/1331/addCustomFieldSetting \
--data-urlencode "custom_field=124578" \
--data-urlencode "is_important=true"

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

Remove a custom field setting from a project

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/projects/1331/removeCustomFieldSetting \
--data-urlencode "custom_field=124578"

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

POST    /workspaces/workspace-id/projects

If the workspace for your project is an organization, you must also supply a team to share the project with.

Returns the full record of the newly created project.

Parameter Description
workspace 1331 Required: The workspace or organization to create the project in.

POST    /teams/team-id/projects

Creates a project shared with the given team.

Returns the full record of the newly created project.

Parameter Description
team 14916 Required: The team to create the project in.

GET SINGLE PROJECT

GET    /projects/project-id

Returns the complete project record for a single project.

Parameter Description
project 13579 Required: The project to get.

Show a specific project.

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

# Response
HTTP/1.1 200
{
  "data": {
    "notes": "These are things we want to purchase.",
    "null": "...",
    "id": 1331,
    "name": "Things to Buy"
  }
}

Get visible tasks on a project.

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

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 2001,
      "name": "Catnip"
    },
    {
      "id": 2002,
      "name": "Kitty litter"
    },
    "~..."
  ]
}

UPDATE A PROJECT

PUT    /projects/project-id

A specific, existing project can be updated by making a PUT request on the URL for that project. 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 project record.

Parameter Description
project 13579 Required: The project to update.
# Request
curl --request PUT -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/projects/1331 \
--data-urlencode "notes=These are things we NEED to purchase."

# Response
HTTP/1.1 200
{
  "data": {
    "notes": "These are things we NEED to purchase.",
    "null": "...",
    "id": 1331,
    "name": "Things to Buy"
  }
}

DELETE A PROJECT

DELETE    /projects/project-id

A specific, existing project can be deleted by making a DELETE request on the URL for that project.

Returns an empty data record.

Parameter Description
project 13579 Required: The project to delete.
# Request
curl --request DELETE -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/projects/1331

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

QUERY FOR PROJECTS

GET    /projects

Returns the compact project records for some filtered set of projects. Use one or more of the parameters provided to filter the projects returned.

Parameter Description
workspace 1331 The workspace or organization to filter projects on.
team 14916 The team to filter projects on.
archived false Only return projects whose archived field takes on the value of this parameter.

Show a specific project.

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

# Response
HTTP/1.1 200
{
  "data": {
    "notes": "These are things we want to purchase.",
    "null": "...",
    "id": 1331,
    "name": "Things to Buy"
  }
}

Get visible tasks on a project.

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

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 2001,
      "name": "Catnip"
    },
    {
      "id": 2002,
      "name": "Kitty litter"
    },
    "~..."
  ]
}

GET    /workspaces/workspace-id/projects

Returns the compact project records for all projects in the workspace.

Parameter Description
workspace 1331 Required: The workspace or organization to find projects in.
archived false Only return projects whose archived field takes on the value of this parameter.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/workspaces/14916/projects

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 1331,
      "name": "Things to buy"
    },
    {
      "id": 14641,
      "name": "Cat Stuff"
    },
    "~..."
  ]
}

GET    /teams/team-id/projects

Returns the compact project records for all projects in the team.

Parameter Description
team 14916 Required: The team to find projects in.
archived false Only return projects whose archived field takes on the value of this parameter.

GET PROJECT TASKS

GET    /projects/project-id/tasks

Returns the compact task records for all tasks within the given project, ordered by their priority within the project. Tasks can exist in more than one project at a time.

Parameter Description
project 13579 Required: The project in which to search for tasks.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/projects/1331/tasks

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 2001,
      "name": "Catnip"
    },
    {
      "id": 2002,
      "name": "Kitty litter"
    },
    "~..."
  ]
}

WORK WITH PROJECT SECTIONS

Sections are list items that end with a colon character : or columns in a board layout. The memberships property of a task contains the project/section pairs to which a task belongs when applicable.

Deprecation warning: At this time, sections in a list-layout project are manipulated as if they were tasks, i.e. reordering a section involves moving the section (and all of its tasks if they are to remain in that section) to a new location in a project. (see Task, Project, and Section Associations for more information). This method of manipulating sections as if they are tasks will soon be deprecated in favor of the methods described in the Sections resource.

MODIFY CUSTOM FIELD SETTINGS

POST    /projects/project-id/addCustomFieldSetting

Create a new custom field setting on the project.

Parameter Description
project 13579 Required: The project to associate the custom field with
custom_field 124578 Required: The id of the custom field to associate with this project.
is_important false Whether this field should be considered important to this project.
insert_before 258147 An id of a Custom Field Settings on this project, before which the new Custom Field Settings will be added. insert_before and insert_after parameters cannot both be specified.
insert_after 258147 An id of a Custom Field Settings on this project, after which the new Custom Field Settings will be added. insert_before and insert_after parameters cannot both be specified.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/projects/1331/addCustomFieldSetting \
--data-urlencode "custom_field=124578" \
--data-urlencode "is_important=true"

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

POST    /projects/project-id/removeCustomFieldSetting

Remove a custom field setting on the project.

Parameter Description
project 13579 Required: The project to associate the custom field with
custom_field 124578 The id of the custom field to remove from this project.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/projects/1331/removeCustomFieldSetting \
--data-urlencode "custom_field=124578"

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