Asana is a work tracking and collaboration tool. This guide is designed to give developers building on Asana’s API a brief overview of how Asana is structured. It’s not meant to be exhaustive and may be too basic for experienced Asana users, but read on if you’re not a user of Asana who uses it regularly. The intention is to describe the fundamental elements of Asana to help you scope apps and avoid common points of confusion.

How work in Asana is organized

Tasks

Tasks are the basic unit of action in Asana. Tasks have many fields including a single assignee, name, notes, followers, likes, and comments. Tasks inherit custom fields from their parent project(s). Custom fields values are set for each individual task.

In addition to standard Create / Read / Update / Delete operations, there are a few things to watch out for when working with tasks:

  • Tasks can be orphaned and belong to no projects, they can belong to one project, or they can be multi-homed across two or more projects. The memberships field is a collection of the projects with which the task is associated.
  • Tasks can be multi-homed as subtasks. For example, task A can be in project B and the same task A can also be a subtask of task C.

  • Tasks API documentation

  • Tasks in the Asana Product Guide

Projects

A project is a collection of tasks that can be viewed as a list, board, timeline, and calendar. Projects can only exist in a single organization or workplace and only belong to a single team. Projects can be public in the team or private to project members. Among the many fields associated with projects, they can have global (shared across the organization) or local (project-specific) custom fields. A project’s custom fields will be displayed on each task within the project.

Portfolios

Portfolios are collections of projects (or other portfolios). Custom fields can be added to portfolios in addition to standard fields that are displayed on every portfolio. These fields provide a high-level overview of the status of each project within the portfolio.

Subtasks

A subtask is exactly the same as tasks in a project except that one (and only one) of its parents is a task (although subtasks can also simultaneously be organized into projects). To check if a task has a subtask, include the num_subtasks field when fetching the parent task.

Things to note when working with subtasks:

Asana object hierarchy

How users of Asana are organized

Workspaces

A workspace is the highest-level organizational unit in Asana. All projects, tasks, and teams have an associated workspace.

Organizations

An organization is a special kind of workspace that represents a company. Organizations connect all the employees at a company using Asana in a single space based on the company’s shared email domain. In an organization, you can group your projects into teams.

Teams

Teams are a subset of users in an organization who collaborate on projects together. Every project in an organization is associated with one team. Team conversations are not currently available in the API.

Users

A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks. Asana accounts are free and tied to individuals; Asana accounts grant access to one or more shared Workspaces and Organizations to collaborate with other Asana users.

Guest Users

Users can invite clients, contractors, customers, or anyone else who does not have an email address at an approved Organization email domain. These users join as Organization Guests. Guests have limited access in an Organization — they can only see what’s explicitly shared with them.

Note: it can be advantageous to use guests to create bot accounts. Due to the access restrictions, bots created from a guest account Personal Access Token can be given fine-grained access to only the data that it needs to use.