> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# Asana

> Test an agent against Asana's REST API for projects, sections, tasks, subtasks, comments and task search.

The Asana replica implements 23 endpoints of REST API 1.0. You can assign tasks, move them between sections, add comments and mark work complete. Its key is `asana`.

## Connect

| Variable | Value |
| - | - |
| `ASANA_API_URL` | Base URL ending in `/api/1.0`. Append paths such as `/tasks`. |
| `ASANA_ACCESS_TOKEN` | Fake access token. Send `Authorization: Bearer <token>`. |

```js Node theme={null}
const headers = { Authorization: 'Bearer ' + process.env.ASANA_ACCESS_TOKEN, 'Content-Type': 'application/json' };
const me = (await (await fetch(process.env.ASANA_API_URL + '/users/me', { headers })).json()).data;
const { data: tasks } = await (await fetch(process.env.ASANA_API_URL + '/tasks?assignee=me&workspace=' + me.workspaces[0].gid + '&completed_since=now&opt_fields=name,due_on,projects.name', { headers })).json();
```

This is the request sequence `ancha connect asana --lang ts` prints. Wrap JSON write bodies in `data`, for example `{"data": {"name": "Follow up on the CSV export"}}`.

## Endpoints

| Method | Path | Support |
| - | - | - |
| `GET` | `/api/1.0/users` | partial: compact records unless `opt_fields`; `limit` and `offset` pages with `next_page` |
| `GET` | `/api/1.0/users/{user_gid}` | partial: a GID, an email or `me` |
| `GET` | `/api/1.0/workspaces` | partial |
| `GET` | `/api/1.0/workspaces/{workspace_gid}` | partial |
| `GET` | `/api/1.0/workspaces/{workspace_gid}/tasks/search` | partial: `text`, `assignee.any`/`assignee.not`, `projects.any`/`projects.not`, `sections.any`, `completed`, `is_subtask`, `due_on`, `created_at` and `modified_at` ranges, `sort_by` |
| `GET` | `/api/1.0/projects` | partial: `archived` filter; compact records unless `opt_fields`; `limit` and `offset` pages with `next_page` |
| `GET` | `/api/1.0/projects/{project_gid}` | partial |
| `GET` | `/api/1.0/projects/{project_gid}/sections` | partial |
| `POST` | `/api/1.0/projects/{project_gid}/sections` | partial: `insert_before` and `insert_after` |
| `GET` | `/api/1.0/projects/{project_gid}/tasks` | partial: board order; `completed_since` |
| `GET` | `/api/1.0/sections/{section_gid}/tasks` | partial |
| `POST` | `/api/1.0/sections/{section_gid}/addTask` | partial: moves a task between sections, next to another task if asked |
| `GET` | `/api/1.0/tasks` | partial: exactly one of `project`, `section`, or `assignee` with `workspace`; `completed_since` and `modified_since` |
| `POST` | `/api/1.0/tasks` | partial: `name`, `notes`, `assignee` (`me`, GID or email), `due_on`/`due_at`, `projects` or `memberships`, `parent`, `followers`; activity stories |
| `GET` | `/api/1.0/tasks/{task_gid}` | partial: `opt_fields` reaches into nested records (`assignee.email`, `memberships.section.name`) |
| `PUT` | `/api/1.0/tasks/{task_gid}` | partial: name, notes, assignee, due dates, completion; each change leaves a story |
| `DELETE` | `/api/1.0/tasks/{task_gid}` | partial: also deletes subtasks |
| `GET` | `/api/1.0/tasks/{task_gid}/subtasks` | partial |
| `POST` | `/api/1.0/tasks/{task_gid}/subtasks` | partial |
| `GET` | `/api/1.0/tasks/{task_gid}/stories` | partial: comments and activity, oldest first |
| `POST` | `/api/1.0/tasks/{task_gid}/stories` | partial |
| `POST` | `/api/1.0/tasks/{task_gid}/addProject` | partial: with a section and `insert_before` or `insert_after` |
| `POST` | `/api/1.0/tasks/{task_gid}/removeProject` | partial |

Lists return compact records unless you request more fields with `opt_fields`. Use `limit` and `offset` to page through results; `next_page` tells you how to continue. Run `ancha twins coverage asana` for the endpoint notes. Calls outside the coverage return Asana's error shape with `x-ancha-gap: 1`.

## Starter data

The `asana-starter` dataset is the workspace **Acme**, with ten users. Your token belongs to **Ancha Assistant**, `ancha@acme.example`. Four projects hold 17 tasks, including two subtasks.

| Project | Starting work |
| - | - |
| Ridgeway Robotics pilot | The kickoff is done. Victor is reducing warehouse sync time, Greg has the pipeline dashboard task, and Mike has onboarding and the missing CSV export. Sections: To do, In progress, Done. |
| Finance ops | Anna has the Helix invoice address change, the Kestrel renewal invoice with `PO-77120`, the Pinecrest order form and expense report follow-ups. Sections: To do, Waiting, Done. |
| Q4 launches | Ellen owns Scheduled reports beta, with subtasks to send invites and write the spec. Dark mode and SCIM provisioning are planned tasks. Sections: Planned, In progress, Shipped. |
| Orders API reliability | Rachel has the 4.12.1 latency postmortem. Ben's worker concurrency and runbook tasks are done. Sections: To do, In progress, Done. |

Tasks include assignees, due dates, followers and comments. `ancha sandbox configuration --tools asana --json` prints every record.

## Checks

Asana has no state checks. Use [trace checks](https://docs.ancha.io/concepts/checks.md#trace-patterns), for example `{ called: "POST /api/1.0/tasks/*/stories" }` or `{ not_called: "DELETE /api/1.0/tasks/*" }`.

## Limits

* No tags, custom fields, portfolios, goals, teams, attachments, webhooks or events.
* Deleting a task also deletes its subtasks.
* Task lists need a project, a section, or an assignee with a workspace.


## Related topics

- [Tools](https://docs.ancha.io/tools/overview.md)
- [Introduction](https://docs.ancha.io/index.md)
- [Environment variables](https://docs.ancha.io/reference/environment-variables.md)
- [Changelog](https://docs.ancha.io/changelog.md)
- [ancha connect](https://docs.ancha.io/cli/connect.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.