Projects

Update a project

Changed on May 21, 2026

<b>Required scope: </b><code>projects:write</code>

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.

Deprecation notice: Updating the team field is deprecated. When this field is included in the request, the Asana-Change response header will indicate an affected deprecation. Clients should switch to using POST /memberships with { parent: project, member: team } to share a project with a team.

put/projects/{project_gid}

Request

Base URL: https://app.asana.com/api/1.0
URL: https://app.asana.com/api/1.0/projects/{project_gid}
Auth: one of:
- HTTP bearer
- OAuth 2 (authorization code, authorization URL https://app.asana.com/-/oauth_authorize, token URL https://app.asana.com/-/oauth_token, scopes: projects:write)

Query parameters

opt_fieldsstring[]

This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. Properties can include nested fields. To learn more, see the input/output options guide.

Request body

Example request

{
  "data": {
    "gid": "12345",
    "resource_type": "project",
    "name": "Stuff to buy",
    "resource_subtype": "default_project",
    "color": "light-green",
    "icon": "chat_bubbles",
    "created_at": "2012-02-22T02:06:58.147Z",
    "current_status": {
      "gid": "12345",
      "resource_type": "project_status",
      "title": "Status Update - Jun 15",
      "text": "The project is moving forward according to plan...",
      "html_text": "<body>The project <strong>is</strong> moving forward according to plan...</body>",
      "author": {
        "gid": "12345",
        "resource_type": "user",
        "name": "Greg Sanchez"
      },
      "created_at": "2012-02-22T02:06:58.147Z",
      "created_by": {
        "gid": "12345",
        "resource_type": "user",
        "name": "Greg Sanchez"
      },
      "modified_at": "2012-02-22T02:06:58.147Z"
    },
    "current_status_update": {
      "gid": "12345",
      "resource_type": "status_update",
      "title": "Status Update - Jun 15",
      "resource_subtype": "project_status_update"
    },
    "custom_field_settings": [
      {
        "gid": "12345",
        "resource_type": "custom_field_setting",
        "project": {
          "gid": "12345",
          "resource_type": "project",
          "name": "Stuff to buy",
          "resource_subtype": "default_project"
        },
        "parent": {
          "gid": "12345",
          "resource_type": "project",
          "name": "Stuff to buy",
          "resource_subtype": "default_project"
        },
        "custom_field": {
          "gid": "12345",
          "resource_type": "custom_field",
          "name": "Status",
          "enum_options": [
            {
              "gid": "12345",
              "resource_type": "enum_option",
              "name": "Low",
              "enabled": true,
              "color": "blue"
            }
          ],
          "enabled": true,
          "representation_type": "number",
          "id_prefix": "ID",
          "input_restrictions": [
            "task"
          ],
          "date_value": {
            "date": "2024-08-23",
            "date_time": "2024-08-23T22:00:00.000Z"
          },
          "enum_value": {
            "gid": "12345",
            "resource_type": "enum_option",
            "name": "Low",
            "enabled": true,
            "color": "blue"
          },
          "multi_enum_values": [
            {
              "gid": "12345",
              "resource_type": "enum_option",
              "name": "Low",
              "enabled": true,
              "color": "blue"
            }
          ],
          "number_value": 5.2,
          "text_value": "Some Value",
          "display_value": "blue",
          "description": "Development team priority",
          "precision": 2,
          "format": "custom",
          "currency_code": "EUR",
          "custom_label": "gold pieces",
          "custom_label_position": "suffix",
          "is_global_to_workspace": true,
          "has_notifications_enabled": true,
          "asana_created_field": "priority",
          "created_by": {
            "gid": "12345",
            "resource_type": "user",
            "name": "Greg Sanchez"
          },
          "people_value": [
            {
              "gid": "12345",
              "resource_type": "user",
              "name": "Greg Sanchez"
            }
          ],
          "reference_value": [
            {
              "gid": "12345",
              "resource_type": "task",
              "name": "Bug Task"
            }
          ],
          "html_text_value": "<body>Some Value</body>",
          "privacy_setting": "public_with_guests",
          "default_access_level": "user",
          "resource_subtype": "text"
        }
      }
    ],
    "default_view": "calendar",
    "due_date": "2019-09-15",
    "due_on": "2019-09-15",
    "html_notes": "<body>These are things we need to purchase.</body>",
    "members": [
      {
        "gid": "12345",
        "resource_type": "user",
        "name": "Greg Sanchez"
      }
    ],
    "modified_at": "2012-02-22T02:06:58.147Z",
    "notes": "These are things we need to purchase.",
    "privacy_setting": "public_to_workspace",
    "start_on": "2019-09-14",
    "default_access_level": "admin",
    "minimum_access_level_for_customization": "admin",
    "minimum_access_level_for_sharing": "admin",
    "custom_fields": {
      "5678904321": "On Hold",
      "4578152156": "Not Started"
    },
    "html_custom_fields": {
      "5678904321": "<body><strong>Bold text</strong></body>",
      "4578152156": "<body><code>Code block</code></body>"
    },
    "followers": "12345,23456",
    "owner": "12345",
    "team": "12345",
    "custom_type": "12345"
  }
}

Response

Successfully updated the project.

Example response

{
  "data": {
    "gid": "12345",
    "resource_type": "project",
    "name": "Stuff to buy",
    "resource_subtype": "default_project",
    "color": "light-green",
    "icon": "chat_bubbles",
    "created_at": "2012-02-22T02:06:58.147Z",
    "current_status": {
      "gid": "12345",
      "resource_type": "project_status",
      "title": "Status Update - Jun 15",
      "text": "The project is moving forward according to plan...",
      "html_text": "<body>The project <strong>is</strong> moving forward according to plan...</body>",
      "author": {
        "gid": "12345",
        "resource_type": "user",
        "name": "Greg Sanchez"
      },
      "created_at": "2012-02-22T02:06:58.147Z",
      "created_by": {
        "gid": "12345",
        "resource_type": "user",
        "name": "Greg Sanchez"
      },
      "modified_at": "2012-02-22T02:06:58.147Z"
    },
    "current_status_update": {
      "gid": "12345",
      "resource_type": "status_update",
      "title": "Status Update - Jun 15",
      "resource_subtype": "project_status_update"
    },
    "custom_field_settings": [
      {
        "gid": "12345",
        "resource_type": "custom_field_setting",
        "project": {
          "gid": "12345",
          "resource_type": "project",
          "name": "Stuff to buy",
          "resource_subtype": "default_project"
        },
        "parent": {
          "gid": "12345",
          "resource_type": "project",
          "name": "Stuff to buy",
          "resource_subtype": "default_project"
        },
        "custom_field": {
          "gid": "12345",
          "resource_type": "custom_field",
          "name": "Status",
          "enum_options": [
            {
              "gid": "12345",
              "resource_type": "enum_option",
              "name": "Low",
              "enabled": true,
              "color": "blue"
            }
          ],
          "enabled": true,
          "representation_type": "number",
          "id_prefix": "ID",
          "input_restrictions": [
            "task"
          ],
          "date_value": {
            "date": "2024-08-23",
            "date_time": "2024-08-23T22:00:00.000Z"
          },
          "enum_value": {
            "gid": "12345",
            "resource_type": "enum_option",
            "name": "Low",
            "enabled": true,
            "color": "blue"
          },
          "multi_enum_values": [
            {
              "gid": "12345",
              "resource_type": "enum_option",
              "name": "Low",
              "enabled": true,
              "color": "blue"
            }
          ],
          "number_value": 5.2,
          "text_value": "Some Value",
          "display_value": "blue",
          "description": "Development team priority",
          "precision": 2,
          "format": "custom",
          "currency_code": "EUR",
          "custom_label": "gold pieces",
          "custom_label_position": "suffix",
          "is_global_to_workspace": true,
          "has_notifications_enabled": true,
          "asana_created_field": "priority",
          "created_by": {
            "gid": "12345",
            "resource_type": "user",
            "name": "Greg Sanchez"
          },
          "people_value": [
            {
              "gid": "12345",
              "resource_type": "user",
              "name": "Greg Sanchez"
            }
          ],
          "reference_value": [
            {
              "gid": "12345",
              "resource_type": "task",
              "name": "Bug Task"
            }
          ],
          "html_text_value": "<body>Some Value</body>",
          "privacy_setting": "public_with_guests",
          "default_access_level": "user",
          "resource_subtype": "text"
        }
      }
    ],
    "default_view": "calendar",
    "due_date": "2019-09-15",
    "due_on": "2019-09-15",
    "html_notes": "<body>These are things we need to purchase.</body>",
    "members": [
      {
        "gid": "12345",
        "resource_type": "user",
        "name": "Greg Sanchez"
      }
    ],
    "modified_at": "2012-02-22T02:06:58.147Z",
    "notes": "These are things we need to purchase.",
    "privacy_setting": "public_to_workspace",
    "start_on": "2019-09-14",
    "default_access_level": "admin",
    "minimum_access_level_for_customization": "admin",
    "minimum_access_level_for_sharing": "admin",
    "custom_fields": [
      {
        "gid": "12345",
        "resource_type": "custom_field",
        "name": "Status",
        "enum_options": [
          {
            "gid": "12345",
            "resource_type": "enum_option",
            "name": "Low",
            "enabled": true,
            "color": "blue"
          }
        ],
        "enabled": true,
        "representation_type": "number",
        "id_prefix": "ID",
        "input_restrictions": [
          "task"
        ],
        "date_value": {
          "date": "2024-08-23",
          "date_time": "2024-08-23T22:00:00.000Z"
        },
        "enum_value": {
          "gid": "12345",
          "resource_type": "enum_option",
          "name": "Low",
          "enabled": true,
          "color": "blue"
        },
        "multi_enum_values": [
          {
            "gid": "12345",
            "resource_type": "enum_option",
            "name": "Low",
            "enabled": true,
            "color": "blue"
          }
        ],
        "number_value": 5.2,
        "text_value": "Some Value",
        "display_value": "blue"
      }
    ],
    "completed_at": "2012-02-22T02:06:58.147Z",
    "completed_by": {
      "gid": "12345",
      "resource_type": "user",
      "name": "Greg Sanchez"
    },
    "followers": [
      {
        "gid": "12345",
        "resource_type": "user",
        "name": "Greg Sanchez"
      }
    ],
    "owner": {
      "gid": "12345",
      "resource_type": "user",
      "name": "Greg Sanchez"
    },
    "team": {
      "gid": "12345",
      "resource_type": "team",
      "name": "Marketing"
    },
    "permalink_url": "https://app.asana.com/1/12345/project/123456789",
    "project_brief": {
      "gid": "12345",
      "resource_type": "project_brief"
    },
    "created_from_template": {
      "gid": "12345",
      "resource_type": "project_template",
      "name": "Packing list"
    },
    "workspace": {
      "gid": "12345",
      "resource_type": "workspace",
      "name": "My Company Workspace"
    },
    "custom_type": {
      "gid": "12345",
      "resource_type": "custom_type",
      "name": "Bug ticket",
      "asana_created_type_identifier": "COMMAND_TICKET"
    }
  }
}

Changes

May 21, 2026b3dcd9ce0bf2 Revision changes
- breaking
  request property /////////////////////// was restricted to a list of enum values
- breaking
  request property //////////////// was restricted to a list of enum values
- warning
  added the new goal enum value to the /////////////////////// response property for the response status
- warning
  added the new goal enum value to the //////////////// response property for the response status
- warning
  added the new goal enum value to the ///// response property for the response status
- warning
  added the new portfolio enum value to the /////////////////////// response property for the response status
- warning
  added the new portfolio enum value to the //////////////// response property for the response status
- warning
  added the new portfolio enum value to the ///// response property for the response status
- warning
  added the new project enum value to the /////////////////////// response property for the response status
- warning
  added the new project enum value to the //////////////// response property for the response status
- warning
  added the new project enum value to the ///// response property for the response status
- warning
  added the new reference enum value to the ////////////////////// response property for the response status
- warning
  added the new reference enum value to the ////////////////////// response property for the response status
- warning
  added the new reference enum value to the //// response property for the response status
- warning
  added the new reference enum value to the //// response property for the response status
- warning
  added the new task enum value to the /////////////////////// response property for the response status
- warning
  added the new task enum value to the //////////////// response property for the response status
- warning
  added the new task enum value to the ///// response property for the response status
- info
  added the new goal enum value to the request property ///////////////////////
- info
  added the new goal enum value to the request property ////////////////
- info
  added the new portfolio enum value to the request property ///////////////////////
- info
  added the new portfolio enum value to the request property ////////////////
- info
  added the new project enum value to the request property ///////////////////////
- info
  added the new project enum value to the request property ////////////////
- info
  added the new reference enum value to the request property //////////////////////
- info
  added the new reference enum value to the request property //////////////////////
- info
  added the new task enum value to the request property ///////////////////////
- info
  added the new task enum value to the request property ////////////////
Apr 28, 2026b04e9dcf7c00 Revision changes
- info
  added the enum value custom_field_settings.custom_field.html_text_value to the property items/ of the query request parameter opt_fields
- info
  added the optional property /////////////// to the response with the status

Operation history