/asana-api

name: asana-api
description: Read and manage Asana tasks, projects, sections, comments, and workspaces. Use this whenever the user wants to list or search tasks, create or update a task, complete a task, comment on a task, move tasks between projects or sections, look up a project or workspace, or ask "what's on my Asana list" — even if they don't say "API". Also use it for any app.asana.com URL or an Asana task/project gid. Always start from this skill when interacting with this service — its bundled scripts and recipes are the fastest path.

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:

• **The `data` envelope.** Reads return `{"data": ...}` (object or array); writes send

`{"data": {...}}` and return the result under `data`. An error replaces `data` with `errors` (see Error handling). Project `.data`, and check `.errors` when it's missing.

• **`gid`, not name.** Everything is referenced by its string `gid` — resolve names to gids first

(workspaces, projects, users, tags; recipe 9).

• **`opt_fields` for fields.** Compact records carry only `gid`, `name`, `resource_type`. Add a

comma-separated `opt_fields` to expand, with dot-notation for relations (`assignee.name`, `memberships.section.name`); `gid` is always returned. On POST/PUT, nest options in an `options` object beside `data`.

Core operations

1. List tasks (`scripts/asana_tasks.sh`)

Run through the bundled script (path is relative to this skill's directory): it GETs `/tasks` filtered by project, tag, section, or assignee+workspace, sends an `opt_fields` list, follows `next_page.offset` through every page, and emits TSV or JSONL.

scripts/asana_tasks.sh --project 1201234567890123 --limit 200
scripts/asana_tasks.sh --assignee me --workspace 1209876543210987 --completed-since now

• Exactly one selector is required: `--project GID`, `--tag GID`, `--section GID`, or

`--assignee GID --workspace GID` (assignee needs a workspace). `--assignee me` resolves the caller via `/users/me`.

• `--completed-since WHEN` — ISO 8601, or `now` to show only incomplete tasks (omit to include all).
• `--fields LIST` — `opt_fields` to request. The TSV columns are fixed (gid, name, completed,

assignee, due_on, permalink_url); extra fields appear only in `--json` output.

• `--limit N` caps tasks fetched (default 100, `0` = everything); `--page-size N` sets the

per-request page (1-100, default 100). Fetched count and any truncation warning go to stderr.

• `--json` emits one raw task object per line instead of TSV.
• Exit codes: `0` success, `1` request failed / API error / bad arguments (the API's own

`errors[].message` is printed to stderr).

If the script errors, read it — it's plain `curl` + `jq` — and debug against `references/api.md`.

2. Get one task

asana "${ASANA_BASE}/tasks/TASK_GID?opt_fields=name,notes,completed,assignee.name,due_on,projects.name,tags.name,parent.name,num_subtasks,custom_fields.name,custom_fields.display_value,permalink_url" \
  | jq '.data'

With no `opt_fields` you get only the compact record. Read a task's comments with recipe 5.

3. Create a task

Fields nest under `data`. One of `workspace`, `projects`, or `parent` is required (a standalone task needs a `workspace`).

asana -X POST "${ASANA_BASE}/tasks" -d '{
  "data": {
    "name": "Draft the launch checklist",
    "notes": "Plain-text body. Use html_notes for rich text.",
    "workspace": "1209876543210987",
    "projects": ["1201234567890123"],
    "assignee": "me",
    "due_on": "2026-06-15",
    "followers": ["1200000000000001"]
  }
}' | jq '.data | {gid, name, permalink_url}'

`assignee` and `followers` take user gids (or `me`); `due_on` is a date, `due_at` an ISO 8601 timestamp. Use `html_notes` for rich text (Asana's HTML subset). Custom-field values go in `custom_fields: {"FIELD_GID": value}`.

4. Update or complete a task

PUT replaces only the fields you send (still wrapped in `data`). You complete a task by setting `completed` — there i