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:

Add a custom field to a project

Remove a custom field from a project

Get a project's custom fields

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.

Property	Type	Description
`gid`	string	Globally unique identifier of the resource, as a string.
`resource_type`	string	The base type of this resource.
`name`	string	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.

{
  "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.

Property	Type	Description
`gid`	string	Globally unique identifier of the resource, as a string.
`resource_type`	string	The base type of this resource.
`archived`	boolean	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.
`color`	string¦null	Color of the project.
`created_at`	string(date-time)	The time at which this resource was created.
`current_status`	object	Deprecated: 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`.`gid`	string	Globally unique identifier of the resource, as a string.
`current_status`.`resource_type`	string	The base type of this resource.
`current_status`.`author`	object	A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
`current_status`.`author`.`gid`	string	Globally unique identifier of the resource, as a string.
`current_status`.`author`.`resource_type`	string	The base type of this resource.
`current_status`.`author`.`name`	string	Read-only except when same user as requester. The user’s name.
`current_status`.`color`	string	The color associated with the status update.
`current_status`.`created_at`	string(date-time)	The time at which this resource was created.
`current_status`.`created_by`	object	A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
`current_status`.`created_by`.`gid`	string	Globally unique identifier of the resource, as a string.
`current_status`.`created_by`.`resource_type`	string	The base type of this resource.
`current_status`.`created_by`.`name`	string	Read-only except when same user as requester. The user’s name.
`current_status`.`html_text`	string	Opt in. The text content of the status update with formatting as HTML.
`current_status`.`modified_at`	string(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`.`text`	string	The text content of the status update.
`current_status`.`title`	string	The title of the project status update.
`current_status_update`	object	A 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`.`gid`	string	Globally unique identifier of the resource, as a string.
`current_status_update`.`resource_type`	string	The base type of this resource.
`current_status_update`.`resource_subtype`	string	The 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_subtype`s for `status` objects represent the type of their parent.
`current_status_update`.`title`	string	The title of the status update.
`custom_field_settings`	[object]	Array of custom field settings (in compact form).
» `{}`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`resource_type`	string	The base type of this resource.
» `{}`.`asana_created_field`	string¦null	Conditional. A unique identifier to associate this field with the template source of truth.
» `{}`.`custom_field`	object	The custom field that is applied to the `parent`.
» `{}`.`custom_field`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`custom_field`.`resource_type`	string	The base type of this resource.
» `{}`.`custom_field`.`created_by`	object	A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
» `{}`.`custom_field`.`created_by`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`custom_field`.`created_by`.`resource_type`	string	The base type of this resource.
» `{}`.`custom_field`.`created_by`.`name`	string	Read-only except when same user as requester. The user’s name.
» `{}`.`custom_field`.`currency_code`	string¦null	ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`.
» `{}`.`custom_field`.`custom_label`	string¦null	This 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_position`	string	Only 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_value`	object	Conditional. 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`.`date`	string(date)	A string representing the date in YYYY-MM-DD format.
» `{}`.`custom_field`.`date_value`.`date_time`	string(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`.`description`	string	Opt in. The description of the custom field.
» `{}`.`custom_field`.`display_value`	string¦null	A 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`.`enabled`	boolean	Conditional. 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.
»» `{}`.`gid`	string	Globally unique identifier of the resource, as a string.
»» `{}`.`resource_type`	string	The base type of this resource.
»» `{}`.`color`	string	The color of the enum option. Defaults to `none`.
»» `{}`.`enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
»» `{}`.`name`	string	The name of the enum option.
» `{}`.`custom_field`.`enum_value`	object	Conditional. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field.
» `{}`.`custom_field`.`enum_value`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`custom_field`.`enum_value`.`resource_type`	string	The base type of this resource.
» `{}`.`custom_field`.`enum_value`.`color`	string	The color of the enum option. Defaults to `none`.
» `{}`.`custom_field`.`enum_value`.`enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
» `{}`.`custom_field`.`enum_value`.`name`	string	The name of the enum option.
» `{}`.`custom_field`.`format`	string	The format of this custom field.
» `{}`.`custom_field`.`has_notifications_enabled`	bolean	Conditional. 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_workspace`	boolean	This 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.
»» `{}`.`gid`	string	Globally unique identifier of the resource, as a string.
»» `{}`.`resource_type`	string	The base type of this resource.
»» `{}`.`color`	string	The color of the enum option. Defaults to `none`.
»» `{}`.`enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
»» `{}`.`name`	string	The name of the enum option.
» `{}`.`custom_field`.`name`	string	The name of the custom field.
» `{}`.`custom_field`.`number_value`	number	Conditional. 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.
»» `{}`.`gid`	string	Globally unique identifier of the resource, as a string.
»» `{}`.`resource_type`	string	The base type of this resource.
»» `{}`.`name`	string	Read-only except when same user as requester. The user’s name.
» `{}`.`custom_field`.`precision`	integer	Only 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_subtype`	string	The type of the custom field. Must be one of the given values.
» `{}`.`custom_field`.`text_value`	string	Conditional. This string is the value of a `text` custom field.
» `{}`.`custom_field`.`type`	string	Deprecated: new integrations should prefer the `resource_subtype` field. The type of the custom field. Must be one of the given values.
» `{}`.`is_important`	boolean	`is_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.
» `{}`.`parent`	object	The 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`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`parent`.`resource_type`	string	The base type of this resource.
» `{}`.`parent`.`name`	string	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.
» `{}`.`project`	object	Deprecated: new integrations should prefer the `parent` field. The id of the project that this custom field settings refers to.
» `{}`.`project`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`project`.`resource_type`	string	The base type of this resource.
» `{}`.`project`.`name`	string	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.
`default_access_level`	string	The 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_view`	string	The default view (list, board, calendar, or timeline) of a project.
`due_date`	string(date-time)¦null	Deprecated: new integrations should prefer the `due_on` field.
`due_on`	string(date-time)¦null	The day on which this project is due. This takes a date with format YYYY-MM-DD.
`html_notes`	html_notes	Opt in. The notes of the project with formatting as HTML.
`members`	[object]	Array of users who are members of this project.
» `{}`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`resource_type`	string	The base type of this resource.
» `{}`.`name`	string	Read-only except when same user as requester. The user’s name.
`modified_at`	string(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.
`name`	string	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.
`notes`	string	Free-form textual information associated with the project (ie., its description).
`public`	boolean	Deprecated: new integrations should use `privacy_setting` instead True if the project is public to its team.
`start_on`	string(date)¦null	The 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.
`workspace`	object	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.
`workspace`.`gid`	string	Globally unique identifier of the resource, as a string.
`workspace`.`resource_type`	string	The base type of this resource.
`workspace`.`name`	string	The name of the workspace.
`completed`	boolean	True if the project is currently marked complete, false if not.
`completed_at`	string(date-time)¦null	The time at which this project was completed, or null if the project is not completed.
`completed_by`	object	A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
`completed_by`.`gid`	string	Globally unique identifier of the resource, as a string.
`completed_by`.`resource_type`	string	The base type of this resource.
`completed_by`.`name`	string	Read-only except when same user as requester. The user’s name.
`created_from_template`	object¦null	Opt 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`.`gid`	string	Globally unique identifier of the resource, as a string.
`created_from_template`.`resource_type`	string	The base type of this resource.
`created_from_template`.`name`	string	Name of the project template.
`custom_fields`	[object]	Array of custom fields.
» `{}`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`resource_type`	string	The base type of this resource.
» `{}`.`date_value`	object	Conditional. 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`.`date`	string	A string representing the date in YYYY-MM-DD format.
» `{}`.`date_value`.`date_time`	string	A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`.
» `{}`.`display_value`	string¦null	A 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.
» `{}`.`enabled`	boolean	Conditional. 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.
»» `{}`.`gid`	string	Globally unique identifier of the resource, as a string.
»» `{}`.`resource_type`	string	The base type of this resource.
»» `{}`.`color`	string	The color of the enum option. Defaults to `none`.
»» `{}`.`enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
»» `{}`.`name`	string	The name of the enum option.
» `{}`.`enum_value`	object	Conditional. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field.
» `{}`.`enum_value`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`enum_value`.`resource_type`	string	The base type of this resource.
» `{}`.`enum_value`.`color`	string	The color of the enum option. Defaults to `none`.
» `{}`.`enum_value`.`enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
» `{}`.`enum_value`.`name`	string	The 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.
»» `{}`.`gid`	string	Globally unique identifier of the resource, as a string.
»» `{}`.`resource_type`	string	The base type of this resource.
»» `{}`.`color`	string	The color of the enum option. Defaults to `none`.
»» `{}`.`enabled`	boolean	Whether or not the enum option is a selectable value for the custom field.
»» `{}`.`name`	string	The name of the enum option.
» `{}`.`name`	string	The name of the custom field.
» `{}`.`number_value`	number	Conditional. This number is the value of a `number` custom field.
» `{}`.`resource_subtype`	string	The type of the custom field. Must be one of the given values.
» `{}`.`text_value`	string	Conditional. This string is the value of a `text` custom field.
» `{}`.`type`	string	Deprecated: 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.
» `{}`.`gid`	string	Globally unique identifier of the resource, as a string.
» `{}`.`resource_type`	string	The base type of this resource.
» `{}`.`name`	string	Read-only except when same user as requester. The user’s name.
`icon`	string¦null	The icon for a project.
`owner`	object	A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
`owner`.`gid`	string	Globally unique identifier of the resource, as a string.
`owner`.`resource_type`	string	The base type of this resource.
`owner`.`name`	string	_Read-only except when same user as requester. The user’s name.
`permalink_url`	string	A URL that points directly to the object within Asana.
`project_brief`	object¦null	Opt in. The project brief associated with this project.
`project_brief`.`gid`	string	Globally unique identifier of the resource, as a string.
`project_brief`.`resource_type`	string	The base type of this resource.
`privacy_setting`	string	The privacy setting of the project. Can be one of: `public_to_workspace`, `private_to_team`, `private` Note: Administrators in your organization may restrict the values of `privacy_setting`.
`team`	object	The team that this project is shared with.
`team`.`gid`	string	Globally unique identifier of the resource, as a string.
`team`.`resource_type`	string	The base type of this resource.
`team`.`name`	string	The 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"
    }
  }
}

Projects

📘
Operating on user task lists

ProjectCompact

Project

📘
`200` response schema

📘Operating on user task lists

ProjectCompact

Project

📘200 response schema

📘
Operating on user task lists

📘
`200` response schema