Tags

A tag is a label that can be attached to any task in Asana. It exists in a single workspace or organization.

Tags have some metadata associated with them, but it is possible that we will simplify them in the future so it is not encouraged to rely too heavily on it. Unlike projects, tags do not provide any ordering on the tasks they are associated with.

Tags have the following fields:

Field Description
id 1234 Read-only. Globally unique ID of the tag.
created_at '2012-02-22T02:06:58.147Z' Read-only. The time at which this tag was created.
followers [ { id: 1123, name: 'Mittens' }, ... ] Read-only. Array of users following this tag.
name 'Stuff to buy' Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.
color 'dark-purple' Color of the tag. Must be either null or one of: dark-pink, dark-green, dark-blue, dark-red, dark-teal, dark-brown, dark-orange, dark-purple, dark-warm-gray, light-pink, light-green, light-blue, light-red, light-teal, light-yellow, light-orange, light-purple, light-warm-gray.
notes 'These are things we need to purchase.' More detailed, free-form textual information associated with the tag.
workspace { id: 14916, name: 'My Workspace' } Create-only. The workspace or organization this tag is associated with. Once created, tags cannot be moved to a different workspace. This attribute can only be specified at creation time.

CREATE A TAG

POST    /tags

Creates a new tag in a workspace or organization.

Every tag 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.

Returns the full record of the newly created tag.

Parameter Description
workspace 1331 Required: The workspace or organization to create the tag in.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tags \
--data-urlencode "name=fluffy" \
--data-urlencode "workspace=14916"

# Response
HTTP/1.1 201
{
  "data": {
    "null": "...",
    "id": 1771,
    "name": "fluffy"
  }
}

POST    /workspaces/workspace-id/tags

Creates a new tag in a workspace or organization.

Every tag 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.

Returns the full record of the newly created tag.

Parameter Description
workspace 1331 Required: The workspace or organization to create the tag in.

GET A SINGLE TAG

GET    /tags/tag-id

Returns the complete tag record for a single tag.

Parameter Description
tag 11235 Required: The tag to get.

Show a specific tag.

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tags/1331

# Response
HTTP/1.1 200
{
  "data": {
    "notes": "These are things we want to purchase.",
    "null": "...",
    "id": 1331,
    "name": "Things to Buy"
  }
}

Get all tasks with a tag.

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tags/1331/tasks

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 2001,
      "name": "Catnip"
    },
    {
      "id": 2002,
      "name": "Kitty litter"
    },
    "~..."
  ]
}

UPDATE A TAG

PUT    /tags/tag-id

Updates the properties of a tag. 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 tag record.

Parameter Description
tag 11235 Required: The tag to update.
# Request
curl --request PUT -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tags/1331 \
--data-urlencode "name=Things to Sell"

# Response
HTTP/1.1 200
{
  "data": {
    "null": "...",
    "id": 1331,
    "name": "Things to Sell"
  }
}

QUERY FOR TAGS

GET    /tags

Returns the compact tag records for some filtered set of tags. Use one or more of the parameters provided to filter the tags returned.

Parameter Description
workspace 1331 The workspace or organization to filter tags on.
team 14916 The team to filter tags on.
archived false Only return tags whose archived field takes on the value of this parameter.

Show a specific tag.

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tags/1331

# Response
HTTP/1.1 200
{
  "data": {
    "notes": "These are things we want to purchase.",
    "null": "...",
    "id": 1331,
    "name": "Things to Buy"
  }
}

Get all tasks with a tag.

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tags/1331/tasks

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 2001,
      "name": "Catnip"
    },
    {
      "id": 2002,
      "name": "Kitty litter"
    },
    "~..."
  ]
}

GET    /workspaces/workspace-id/tags

Returns the compact tag records for all tags in the workspace.

Parameter Description
workspace 1331 Required: The workspace or organization to find tags in.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/workspaces/14916/tags

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 1331,
      "name": "Things to buy"
    },
    {
      "id": 14641,
      "name": "Cat Stuff"
    },
    "~..."
  ]
}

GET TASKS WITH TAG

GET    /tags/tag-id/tasks

Returns the compact task records for all tasks with the given tag. Tasks can have more than one tag at a time.

Parameter Description
tag 11235 Required: The tag to fetch tasks from.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tags/1331/tasks

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 2001,
      "name": "Catnip"
    },
    {
      "id": 2002,
      "name": "Kitty litter"
    },
    "~..."
  ]
}