Asana

Asana

Asana organizes work into workspaces containing projects, which contain sections and tasks. Tasks are the atomic unit of work — they carry assignments, due dates, tags, subtasks, and a comment/story stream.

Data Model

• Workspace — top-level container. All resources belong to a workspace. Has a GID, name, and is_organization flag.
• Team — sub-group within an organization workspace. Projects belong to teams.
• Project — a collection of tasks, displayed as list, board, timeline, or calendar. Has sections for grouping. Belongs to a workspace and optionally a team.
• Section — a named grouping within a project (e.g. "To Do", "In Progress", "Done"). Tasks are ordered within sections.
• Task — a unit of work. Has name, notes (description), assignee, due_on/due_at, completed status, tags, custom fields, parent (for subtasks), and memberships (which projects/sections it belongs to).
• Subtask — a task whose parent is another task. Arbitrarily nestable.
• Story — an entry in a task's activity feed. Can be a comment (type=comment) or system-generated (type=system). Comments have text and html_text.
• Tag — a label applied to tasks across projects. Workspace-scoped.
• User — a person in the workspace. Has name, email, photo, workspaces.

Entity Relationships

Workspace ─┬─ Teams (in organizations) ├─ Projects ─── Sections ─── Tasks ├─ Tags └─ Users

Task ─┬─ Subtasks (recursive) ├─ Stories (comments + system events) ├─ Tags (many-to-many) ├─ Attachments └─ Memberships (project + section placement)

Key Workflows

1. Start with workspaces: Get workspaces to find the workspace GID needed for most operations.
2. Browse projects: List projects in a workspace → get project details → list sections → list tasks in a project.
3. Task management: Create/update/delete tasks. Assign to users, set due dates, add to projects.
4. Search: Search tasks in a workspace by text, assignee, project, completion status, date ranges.
5. Comments: Read stories on a task, add comments.
6. Organization: Use sections to group tasks within projects. Use tags for cross-project labeling.

Gotchas

• opt_fields is critical: By default, Asana returns compact representations (just GID and name). Use opt_fields to request additional fields like assignee, due_on, completed, notes, etc.
• Workspace GID required: Most list/search operations require a workspace GID. Get it from the authenticated user's workspaces first.
• Pagination: List endpoints use cursor-based pagination. Response includes next_page.offset for the next page. Default limit is 20, max 100.
• Task memberships: A task can belong to multiple projects. The memberships field shows which projects and sections it's in.
• Search is premium-only: The task search endpoint requires a Premium, Business, or Enterprise Asana plan. Returns max 100 results.
• Search is eventually consistent: New/updated tasks may take 10-60 seconds to appear in search results.
• Subtasks are separate: Subtasks don't appear in project task lists by default — they live under their parent task. Query subtasks explicitly.
• due_on vs due_at: due_on is a date (YYYY-MM-DD), due_at is a datetime (ISO 8601). Only one should be set.
• Delete is soft: Deleted tasks go to trash and are recoverable for 30 days.
• Stories vs comments: The stories endpoint returns both comments and system-generated activity. Filter by type=comment for just comments.
• Workspace shape matters for project create: workspace.is_organization=true workspaces are organization workspaces (have teams, support project visibility). is_organization=false are personal workspaces (no teams, no public field). When creating a project in an organization, pass team_gid AND optionally public; without a team, omit public or Asana returns 400 "public: Cannot write this property". The authenticated user profile call already returns workspaces[] with is_organization — list workspaces separately only when you need extra workspace fields.