Project Statuses

A project status is an update on the progress of a particular project, and is sent out to all project followers when created. These updates include both text describing the update and a color code intended to represent the overall state of the project: “green” for projects that are on track, “yellow” for projects at risk, and “red” for projects that are behind.

Project statuses can be created and deleted, but not modified.

Project Statuses have the following fields:
Field Description
id 1234 Read-only. Globally unique ID of the project status update.
title 'Status Update - Jun 15' Read-only. The title of the project status update.
text 'The project is moving forward according to plan...' Read-only. The text content of the status update.
color 'green' 'yellow' 'red' Read-only. The color associated with the status update.
created_by { id: 12345, name: 'Tim Bizarro' } Read-only. The creator of the status update.
created_at '2012-02-22T02:06:58.147Z' Read-only. The time at which the status update was created.

CREATE A STATUS UPDATE

POST    /projects/project-id/project_statuses

Creates a new status update on the project.

Returns the full record of the newly created project status update.

Parameter Description
project 13579 Required: The project on which to create a status update.
text The project is on track to ship next month! Required: The text of the project status update.
color 'green' 'yellow' 'red' Required: The color to associate with the status update. Must be one of "red", "yellow", or "green".
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/projects/1012/project_statuses \
--data-urlencode "text=The project is on track to ship next month!" \
--data-urlencode "color=green"

# Response
HTTP/1.1 201
{
  "data": {
    "id": 18492,
    "title": "Status Update - Jun 15",
    "text": "The project is on track to ship next month!",
    "color": "green",
    "created_by": {
      "id": 1234,
      "name": "Tim Bizarro"
    },
    "created_at": "2018-06-15T18:40:50.902Z"
  }
}

GET STATUS UPDATES FOR A PROJECT

GET    /projects/project-id/project_statuses

Returns the compact project status update records for all updates on the project.

Parameter Description
project 13579 Required: The project to find status updates for.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/projects/1012/project_statuses

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 18492,
      "title": "Status Update - Jun 15"
    },
    {
      "id": 13597,
      "title": "Status Update - May 30"
    },
    "~..."
  ]
}

GET A STATUS UPDATE

GET    /project_statuses/project-status-id

Returns the complete record for a single status update.

Parameter Description
project-status 13597 Required: The project status update to get.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/project_statuses/18492

# Response
HTTP/1.1 200
{
  "data": {
    "id": 18492,
    "title": "Status Update - Jun 15",
    "text": "The project is on track to ship next month!",
    "color": "green",
    "created_by": {
      "id": 1234,
      "name": "Tim Bizarro"
    },
    "created_at": "2018-06-15T18:40:50.902Z"
  }
}

DELETE A STATUS UPDATE

DELETE    /project_statuses/project-status-id

Deletes a specific, existing project status update.

Returns an empty data record.

Parameter Description
project-status 13597 Required: The project status update to delete.
# Request
curl --request DELETE -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/project_statuses/18492

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