asana-api

Asana's REST API is rooted at https://app.asana.com/api/1.0. Three things are true of every call: every object is identified by a string gid (global id), every response wraps its payload in a top-level data key, and write bodies wrap their fields in data too. Most reads return a compact record (gid, name, resource_type) — ask for more with opt_fields.

Resources nest predictably: a workspace (an organization if it has one) holds projects and users; a project holds sections and tasks; a task carries comments and activity as stories, plus subtasks, tags, attachments, and custom fields.

Request setup

Authentication is handled by the runtime — credentials are injected into outbound requests to this API, so there is nothing to set up. Do not try to create, mint, refresh, or validate tokens or keys. Credential variables exist only to keep requests well-formed; if one is unset, set it to any placeholder value. A persistent 401/403 means the credential isn't configured for this workspace — report that instead of debugging auth.

Requests use a bearer token. The base URL is fixed (not per-instance), but workspace/project/task gids are real and part of the path:

export ASANA_TOKEN="placeholder"                 # injected by the runtime; any value works
export ASANA_BASE="https://app.asana.com/api/1.0"

Define a helper once per session:

asana() { curl -sS -H "Authorization: Bearer ${ASANA_TOKEN}" \
  -H "Accept: application/json" -H "Content-Type: application/json" "$@"; }

Sanity check — confirm the token works and find your workspace gids:

asana "${ASANA_BASE}/users/me?opt_fields=name,email,workspaces.name" \
  | jq '.data | {gid, name, email, workspaces: [.workspaces[]? | {gid, name}]}'
# 200 with your user + workspaces → wired up. 401 → credential not configured; report it.

Response conventions

Three patterns repeat across every endpoint below — stated once so the recipes stay short: