Projects

A project represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. A project 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. Currently, the team of a project cannot be changed 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.

📘

Operating on user task lists

You can use certain project endpoints to operate on user task lists (My Tasks) by substituting the {project_gid} with the {user_task_list_gid}. For example, you can perform operations on the custom fields of a user task list by using the following projects endpoints:


ProjectCompact

A Compact object reflects the default fields returned after a successful API request. See input/output options to include more fields in the response.

PropertyTypeDescription
gidstringGlobally unique identifier of the resource, as a string.
resource_typestringThe base type of this resource.
namestringName 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.
{
  "gid": "12345",
  "resource_type": "project",
  "name": "Stuff to buy"
}

Project

📘

200 response schema

For another view of a full project schema, see the example 200 responses when getting a project.

PropertyTypeDescription
gidstringGlobally unique identifier of the resource, as a string.
resource_typestringThe base type of this resource.
archivedbooleanTrue 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.
colorstring¦nullColor of the project.
created_atstring(date-time)The time at which this resource was created.
current_statusobjectDeprecated: new integrations should prefer the status_update resource.

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.
current_status.gidstringGlobally unique identifier of the resource, as a string.
current_status.resource_typestringThe base type of this resource.
current_status.authorobjectA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
current_status.author.gidstringGlobally unique identifier of the resource, as a string.
current_status.author.resource_typestringThe base type of this resource.
current_status.author.namestringRead-only except when same user as requester. The user’s name.
current_status.colorstringThe color associated with the status update.
current_status.created_atstring(date-time)The time at which this resource was created.
current_status.created_byobjectA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
current_status.created_by.gidstringGlobally unique identifier of the resource, as a string.
current_status.created_by.resource_typestringThe base type of this resource.
current_status.created_by.namestringRead-only except when same user as requester. The user’s name.
current_status.html_textstringOpt in. The text content of the status update with formatting as HTML.
current_status.modified_atstring(date-time)The time at which this project status was last modified.

Note: This does not currently reflect any changes in associations such as comments that may have been added or removed from the project status.
current_status.textstringThe text content of the status update.
current_status.titlestringThe title of the project status update.
current_status_updateobjectA status update is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a status_type intended to represent the overall state of the project.
current_status_update.gidstringGlobally unique identifier of the resource, as a string.
current_status_update.resource_typestringThe base type of this resource.
current_status_update.resource_subtypestringThe subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.

The resource_subtypes for status objects represent the type of their parent.
current_status_update.titlestringThe title of the status update.
custom_field_settings[object]Array of custom field settings (in compact form).
» {}.gidstringGlobally unique identifier of the resource, as a string.
» {}.resource_typestringThe base type of this resource.
» {}.asana_created_field string¦nullConditional. A unique identifier to associate this field with the template source of truth.
» {}.custom_fieldobjectThe custom field that is applied to the parent.
» {}.custom_field.gidstringGlobally unique identifier of the resource, as a string.
» {}.custom_field.resource_typestringThe base type of this resource.
» {}.custom_field.created_byobjectA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
» {}.custom_field.created_by.gidstringGlobally unique identifier of the resource, as a string.
» {}.custom_field.created_by.resource_typestringThe base type of this resource.
» {}.custom_field.created_by.namestringRead-only except when same user as requester. The user’s name.
» {}.custom_field.currency_codestring¦nullISO 4217 currency code to format this custom field. This will be null if the format is not currency.
» {}.custom_field.custom_labelstring¦nullThis is the string that appears next to the custom field value. This will be null if the format is not custom.
» {}.custom_field.custom_label_positionstringOnly relevant for custom fields with custom format. This depicts where to place the custom label. This will be null if the format is not custom.
» {}.custom_field.date_valueobjectConditional. Only relevant for custom fields of type date. This object reflects the chosen date (and optionally, time) value of a date custom field. If no date is selected, the value of date_value will be null.
» {}.custom_field.date_value.datestring(date)A string representing the date in YYYY-MM-DD format.
» {}.custom_field.date_value.date_timestring(date-time)A string representing the date in ISO 8601 format. If no time value is selected, the value of date-time will be null.
» {}.custom_field.descriptionstringOpt in. The description of the custom field.
» {}.custom_field.display_valuestring¦nullA string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.
» {}.custom_field.enabledbooleanConditional. Determines if the custom field is enabled or not.
» {}.custom_field.enum_options[object]Conditional. Only relevant for custom fields of type enum. This array specifies the possible values which an enum custom field can adopt. To modify the enum options, refer to working with enum options.
»» {}.gidstringGlobally unique identifier of the resource, as a string.
»» {}.resource_typestringThe base type of this resource.
»» {}.colorstringThe color of the enum option. Defaults to none.
»» {}.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
»» {}.namestringThe name of the enum option.
» {}.custom_field.enum_valueobjectConditional. Only relevant for custom fields of type enum. This object is the chosen value of an enum custom field.
» {}.custom_field.enum_value.gidstringGlobally unique identifier of the resource, as a string.
» {}.custom_field.enum_value.resource_typestringThe base type of this resource.
» {}.custom_field.enum_value.colorstringThe color of the enum option. Defaults to none.
» {}.custom_field.enum_value.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
» {}.custom_field.enum_value.namestringThe name of the enum option.
» {}.custom_field.formatstringThe format of this custom field.
» {}.custom_field.has_notifications_enabledboleanConditional. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field.
» {}.custom_field.is_global_to_workspacebooleanThis flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true.
» {}.custom_field.multi_enum_values[object]Conditional. Only relevant for custom fields of type multi_enum. This object is the chosen values of a multi_enum custom field.
»» {}.gidstringGlobally unique identifier of the resource, as a string.
»» {}.resource_typestringThe base type of this resource.
»» {}.colorstringThe color of the enum option. Defaults to none.
»» {}.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
»» {}.namestringThe name of the enum option.
» {}.custom_field.namestringThe name of the custom field.
» {}.custom_field.number_valuenumberConditional. This number is the value of a number custom field.
» {}.custom_field.people_value[object]Conditional. Only relevant for custom fields of type people. This array of compact user objects reflects the values of a people custom field.
»» {}.gidstringGlobally unique identifier of the resource, as a string.
»» {}.resource_typestringThe base type of this resource.
»» {}.namestringRead-only except when same user as requester. The user’s name.
» {}.custom_field.precisionintegerOnly relevant for custom fields of type ‘Number’. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.
For percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.

The identifier format will always have a precision of 0.
» {}.custom_field.resource_subtypestringThe type of the custom field. Must be one of the given values.
» {}.custom_field.text_valuestringConditional. This string is the value of a text custom field.
» {}.custom_field.typestringDeprecated: new integrations should prefer the resource_subtype field. The type of the custom field. Must be one of the given values.
» {}.is_importantbooleanis_important is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.
» {}.parentobjectThe parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field.
» {}.parent.gidstringGlobally unique identifier of the resource, as a string.
» {}.parent.resource_typestringThe base type of this resource.
» {}.parent.namestringName 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.
» {}.projectobjectDeprecated: new integrations should prefer the parent field. The id of the project that this custom field settings refers to.
» {}.project.gidstringGlobally unique identifier of the resource, as a string.
» {}.project.resource_typestringThe base type of this resource.
» {}.project.namestringName 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.
default_access_levelstringThe default access level for users or teams who join or are added as members to the project. Set to editor by default. Can be one of: admin, editor, commenter, viewer
default_viewstringThe default view (list, board, calendar, or timeline) of a project.
due_datestring(date-time)¦nullDeprecated: new integrations should prefer the due_on field.
due_onstring(date-time)¦nullThe day on which this project is due. This takes a date with format YYYY-MM-DD.
html_noteshtml_notesOpt in. The notes of the project with formatting as HTML.
members[object]Array of users who are members of this project.
» {}.gidstringGlobally unique identifier of the resource, as a string.
» {}.resource_typestringThe base type of this resource.
» {}.namestringRead-only except when same user as requester. The user’s name.
modified_atstring(date-time)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.
namestringName 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.
notesstringFree-form textual information associated with the project (ie., its description).
publicbooleanTrue if the project is public to its team.
start_onstring(date)¦nullThe day on which work for this project begins, or null if the project has no start date. This 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. Additionally, start_on and due_on cannot be the same date.
workspaceobjectCreate-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.
workspace.gidstringGlobally unique identifier of the resource, as a string.
workspace.resource_typestringThe base type of this resource.
workspace.namestringThe name of the workspace.
completedbooleanTrue if the project is currently marked complete, false if not.
completed_atstring(date-time)¦nullThe time at which this project was completed, or null if the project is not completed.
completed_byobjectA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
completed_by.gidstringGlobally unique identifier of the resource, as a string.
completed_by.resource_typestringThe base type of this resource.
completed_by.namestringRead-only except when same user as requester. The user’s name.
created_from_templateobject¦nullOpt in. The project template from which this project was created. If the project was not created from a template, this field will be null.
created_from_template.gidstringGlobally unique identifier of the resource, as a string.
created_from_template.resource_typestringThe base type of this resource.
created_from_template.namestringName of the project template.
custom_fields[object]Array of custom fields.
» {}.gidstringGlobally unique identifier of the resource, as a string.
» {}.resource_typestringThe base type of this resource.
» {}.date_valueobjectConditional. Only relevant for custom fields of type date. This object reflects the chosen date (and optionally, time) value of a date custom field. If no date is selected, the value of date_value will be null.
» {}.date_value.datestringA string representing the date in YYYY-MM-DD format.
» {}.date_value.date_timestringA string representing the date in ISO 8601 format. If no time value is selected, the value of date-time will be null.
» {}.display_valuestring¦nullA string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.
» {}.enabledbooleanConditional. Determines if the custom field is enabled or not.
» {}.enum_options[object]Conditional. Only relevant for custom fields of type enum. This array specifies the possible values which an enum custom field can adopt. To modify the enum options, refer to working with enum options.
»» {}.gidstringGlobally unique identifier of the resource, as a string.
»» {}.resource_typestringThe base type of this resource.
»» {}.colorstringThe color of the enum option. Defaults to none.
»» {}.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
»» {}.namestringThe name of the enum option.
» {}.enum_valueobjectConditional. Only relevant for custom fields of type enum. This object is the chosen value of an enum custom field.
» {}.enum_value.gidstringGlobally unique identifier of the resource, as a string.
» {}.enum_value.resource_typestringThe base type of this resource.
» {}.enum_value.colorstringThe color of the enum option. Defaults to none.
» {}.enum_value.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
» {}.enum_value.namestringThe name of the enum option.
» {}.multi_enum_values[object]Conditional. Only relevant for custom fields of type multi_enum. This object is the chosen values of a multi_enum custom field.
»» {}.gidstringGlobally unique identifier of the resource, as a string.
»» {}.resource_typestringThe base type of this resource.
»» {}.colorstringThe color of the enum option. Defaults to none.
»» {}.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
»» {}.namestringThe name of the enum option.
» {}.namestringThe name of the custom field.
» {}.number_valuenumberConditional. This number is the value of a number custom field.
» {}.resource_subtypestringThe type of the custom field. Must be one of the given values.
» {}.text_valuestringConditional. This string is the value of a text custom field.
» {}.typestringDeprecated: new integrations should prefer the resource_subtype field. The type of the custom field. Must be one of the given values.
followers[object]Array of users following this project. Followers are a subset of members who have opted in to receive "tasks added" notifications for a project.
» {}.gidstringGlobally unique identifier of the resource, as a string.
» {}.resource_typestringThe base type of this resource.
» {}.namestringRead-only except when same user as requester. The user’s name.
iconstring¦nullThe icon for a project.
ownerobjectA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
owner.gidstringGlobally unique identifier of the resource, as a string.
owner.resource_typestringThe base type of this resource.
owner.namestringRead-only except when same user as requester. The user’s name.
permalink_urlstringA URL that points directly to the object within Asana.
project_briefobject¦nullOpt in. The project brief associated with this project.
project_brief.gidstringGlobally unique identifier of the resource, as a string.
project_brief.resource_typestringThe base type of this resource.
teamobjectThe team that this project is shared with.
team.gidstringGlobally unique identifier of the resource, as a string.
team.resource_typestringThe base type of this resource.
team.namestringThe name of the team.
{
  "data": {
    "gid": "12345",
    "resource_type": "task",
    "name": "Stuff to buy",
    "archived": false,
    "color": "light-green",
    "created_at": "2012-02-22T02:06:58.147Z",
    "current_status": {
      "gid": "12345",
      "resource_type": "task",
      "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>",
      "color": "green",
      "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": "task",
      "title": "Status Update - Jun 15",
      "resource_subtype": "project_status_update"
    },
    "custom_field_settings": [
      {
        "gid": "12345",
        "resource_type": "task",
        "project": {
          "gid": "12345",
          "resource_type": "task",
          "name": "Stuff to buy"
        },
        "is_important": false,
        "parent": {
          "gid": "12345",
          "resource_type": "task",
          "name": "Stuff to buy"
        },
        "custom_field": {
          "gid": "12345",
          "resource_type": "task",
          "name": "Status",
          "resource_subtype": "text",
          "type": "text",
          "enum_options": [
            {
              "gid": "12345",
              "resource_type": "task",
              "name": "Low",
              "enabled": true,
              "color": "blue"
            }
          ],
          "enabled": true,
          "date_value": {
            "date": "2024-08-23",
            "date_time": "2024-08-23T22:00:00.000Z"
          },
          "enum_value": {
            "gid": "12345",
            "resource_type": "task",
            "name": "Low",
            "enabled": true,
            "color": "blue"
          },
          "multi_enum_values": [
            {
              "gid": "12345",
              "resource_type": "task",
              "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": "task",
            "name": "Greg Sanchez"
          },
          "people_value": [
            {
              "gid": "12345",
              "resource_type": "task",
              "name": "Greg Sanchez"
            }
          ]
        }
      }
    ],
    "default_access_level": "editor",
    "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.",
    "public": false,
    "start_on": "2019-09-14",
    "workspace": {
      "gid": "12345",
      "resource_type": "workspace",
      "name": "My Company Workspace"
    },
    "custom_fields": [
      {
        "gid": "12345",
        "resource_type": "task",
        "name": "Status",
        "resource_subtype": "text",
        "type": "text",
        "enum_options": [
          {
            "gid": "12345",
            "resource_type": "task",
            "name": "Low",
            "enabled": true,
            "color": "blue"
          }
        ],
        "enabled": true,
        "date_value": {
          "date": "2024-08-23",
          "date_time": "2024-08-23T22:00:00.000Z"
        },
        "enum_value": {
          "gid": "12345",
          "resource_type": "task",
          "name": "Low",
          "enabled": true,
          "color": "blue"
        },
        "multi_enum_values": [
          {
            "gid": "12345",
            "resource_type": "task",
            "name": "Low",
            "enabled": true,
            "color": "blue"
          }
        ],
        "number_value": 5.2,
        "text_value": "Some Value",
        "display_value": "blue"
      }
    ],
    "completed": false,
    "completed_at": "2012-02-22T02:06:58.147Z",
    "completed_by": {
      "gid": "12345",
      "resource_type": "task",
      "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"
    },
    "icon": "chat_bubbles",
    "permalink_url": "https://app.asana.com/0/resource/123456789/list",
    "project_brief": {
      "gid": "12345",
      "resource_type": "task"
    },
    "created_from_template": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Packing list"
    }
  }
}