Sections

A section is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.

Sections are largely a shared idiom in Asana’s API for both list and board views of a project regardless of the project’s layout.

The ‘memberships’ property when getting a task will return the information for the section or the column under ‘section’ in the response.

Sections have the following fields:

Field Description
id 1234 Read-only. Globally unique ID of the section.
name 'Next Actions' The name of the section (i.e. the text displayed as the section header).
project { id: 1234, name: 'Bugs' } Read-only. The project which contains the section.
created_at '2012-02-22T02:06:58.147Z' Read-only. The time at which the section was created.

CREATE A SECTION

POST    /projects/project-id/sections

Creates a new section in a project.

Returns the full record of the newly created section.

Parameter Description
project 13579 Required: The project to create the section in
name 'Next Actions' Required: The text to be displayed as the section name. This cannot be an empty string.

Create a new section on a project

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/projects/1331/sections \
--data-urlencode "name=High Priority:"

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 2001,
      "name": "High Priority:",
      "created_at": "2017-01-17T22:06:39.249Z",
      "project": {
        "id": 1331,
        "name": "Things to buy"
      }
    }
  ]
}

Add or move a section in a project

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/projects/1331/sections/insert \
--data-urlencode "section=2001" \
--data-urlencode "before_section=2002"

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

GET SECTIONS IN A PROJECT

GET    /projects/project-id/sections

Returns the compact records for all sections in the specified project.

Parameter Description
project 13579 Required: The project to get sections from.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/projects/1331/sections

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 2001,
      "name": "High Priority:"
    },
    {
      "id": 2002,
      "name": "Low Priority:"
    },
    "~..."
  ]
}

GET A SINGLE SECTION

GET    /sections/section-id

Returns the complete record for a single section.

Parameter Description
section 97531 Required: The section to get.

UPDATE A SECTION

PUT    /sections/section-id

A specific, existing section 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. (note that at this time, the only field that can be updated is the name field.)

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 section record.

Parameter Description
section 97531 Required: The section to update.
# Request
curl --request PUT -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/sections/2001 \
--data-urlencode "name=High Priority, renamed:"

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 2001,
      "name": "High Priority, renamed:",
      "created_at": "2017-01-17T22:06:39.249Z",
      "project": {
        "id": 1331,
        "name": "Things to buy"
      }
    }
  ]
}

DELETE A SECTION

DELETE    /sections/section-id

A specific, existing section can be deleted by making a DELETE request on the URL for that section.

Note that sections must be empty to be deleted.

The last remaining section in a board view cannot be deleted.

Returns an empty data block.

Parameter Description
section 97531 Required: The section to delete.
# Request
curl --request DELETE -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/sections/2001

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

MOVE A SECTION IN A PROJECT

POST    /projects/project-id/sections/insert

Move sections relative to each other in a board view. One of before_section or after_section is required.

Sections cannot be moved between projects.

At this point in time, moving sections is not supported in list views, only board views.

Returns an empty data block.

Parameter Description
project 13579 Required: The project in which to reorder the given section
section 97531 Required: The section to reorder
before_section 86420 Insert the given section immediately before the section specified by this parameter.
after_section 86420 Insert the given section immediately after the section specified by this parameter.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/projects/1331/sections/insert \
--data-urlencode "section=2001" \
--data-urlencode "before_section=2002"

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