Sign in
Projects

Create a project

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

Create 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.

Deprecation notice: The team parameter and the private_to_team value for privacy_setting are deprecated. When either 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 after creation.

post/projects

Request

  • Base URL: https://app.asana.com/api/1.0
  • URL: https://app.asana.com/api/1.0/projects
  • 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",
    "workspace": "12345",
    "custom_type": "12345"
  }
}

Response

Successfully retrieved projects.

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

No operation changes recorded.