asana
Interact with the Asana REST API using a Personal Access Token in ASANA_PAT. Covers core work management plus portfolios, goals, status updates, webhooks, events, audit logs, attachments, batch reques
SKILL.mdvar/agents/skills/apis/asana/SKILL.md
GitHubInteract with the Asana REST API directly using a Personal Access Token:
- Store the token in
ASANA_PAT. - Send it via the
Authorization: Bearer $ASANA_PATheader. - Never hardcode credentials.
Canonical references
- Main REST reference:
https://developers.asana.com/reference/rest-api-reference - Raw OpenAPI spec:
https://raw.githubusercontent.com/Asana/openapi/master/defs/asana_oas.yaml - Base URL:
https://app.asana.com/api/1.0
Quick auth check
[ -z "$ASANA_PAT" ] && echo "Error: ASANA_PAT not set" || echo "OK: ASANA_PAT is set"
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/workspaces" | jq .
Core API conventions
Response shape
Most Asana responses are wrapped in a top-level data key:
{ "data": { ... } }
For list endpoints:
{ "data": [ ... ], "next_page": { ... } }
Request shape
Most JSON create/update endpoints expect a top-level data object:
{
"data": {
"name": "Example"
}
}
IDs
Asana uses string GIDs everywhere:
- user GIDs
- workspace GIDs
- team GIDs
- project GIDs
- task GIDs
- portfolio GIDs
- goal GIDs
Output options
Common query options:
opt_fields=field1,field2,...pretty=true
opt_fields is recommended since many endpoints return compact objects by default.
Pagination
Common list pagination params:
limit— page size, 1 to 100offset— opaque pagination token, not a numeric index
Do not guess offsets. Reuse the token returned by the previous page.
Coverage map
Commonly used core resources
- Workspaces
- Users
- Teams
- Projects
- Sections
- Tasks
- Subtasks
- Stories/comments
- Tags
- Custom fields
- Attachments
Higher-level planning / reporting resources
- Portfolios
- Goals
- Goal relationships
- Project statuses
- Status updates
- User task lists
- Time tracking entries
- Jobs
Eventing / integration resources
- Webhooks
- Events
- Audit log API
- Batch API
- Exports
Additional API families present in the official spec
The current Asana API also includes these resource families:
- Access requests
- Allocations
- Budgets
- Custom field settings
- Custom types
- Memberships
- Ooo entries
- Organization exports
- Portfolio memberships
- Project briefs
- Project memberships
- Project portfolio settings
- Project templates
- Rates
- Reactions
- Roles
- Rules
- SSPM
- Task templates
- Team memberships
- Time periods
- Time tracking categories
- Timesheet approval statuses
- Typeahead
- Workspace memberships
Recommended discovery flow
When IDs are unknown, discover them in this order:
- List workspaces
- List users and teams in the workspace
- List projects in the workspace or team
- List sections in a project
- List tasks in the project or section
- Then query stories, tags, custom fields, attachments, portfolios, goals, etc.
Workspaces, users, teams
List workspaces
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/workspaces" | jq '.data'
List users
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/users" | jq '.data'
Get a user
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/users/USER_GID" | jq '.data'
List users in a workspace or organization
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/workspaces/WORKSPACE_GID/users" | jq '.data'
List teams in a workspace
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/workspaces/WORKSPACE_GID/teams" | jq '.data'
Get a team
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/teams/TEAM_GID" | jq '.data'
List users in a team
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/teams/TEAM_GID/users" | jq '.data'
Projects and sections
List projects
# Workspace-scoped
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/workspaces/WORKSPACE_GID/projects" | jq '.data'
# Team-scoped
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/teams/TEAM_GID/projects" | jq '.data'
# Generic projects endpoint with filters
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/projects?workspace=WORKSPACE_GID" | jq '.data'
Get a project
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/projects/PROJECT_GID" | jq '.data'
Create or update a project
# Create in workspace
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://app.asana.com/api/1.0/workspaces/WORKSPACE_GID/projects" \
-d '{"data":{"name":"Project Name"}}' | jq '.data'
# Update
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
-H "Content-Type: application/json" \
-X PUT \
"https://app.asana.com/api/1.0/projects/PROJECT_GID" \
-d '{"data":{"name":"Updated Project Name"}}' | jq '.data'
List sections in a project
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/projects/PROJECT_GID/sections" | jq '.data'
Create a section in a project
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://app.asana.com/api/1.0/projects/PROJECT_GID/sections" \
-d '{"data":{"name":"To Do"}}' | jq '.data'
Tasks
Get a task
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/tasks/TASK_GID" | jq '.data'
Use opt_fields to request specific fields:
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/tasks/TASK_GID?opt_fields=name,completed,assignee.name,due_on,projects.name,tags.name,custom_fields.name,custom_fields.display_value" | jq '.data'
List tasks in a project or section
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/projects/PROJECT_GID/tasks" | jq '.data'
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/sections/SECTION_GID/tasks" | jq '.data'
Search tasks in a workspace
This is Asana's main workspace-level search endpoint.
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/workspaces/WORKSPACE_GID/tasks/search?completed=false&assignee=me" | jq '.data'
Commonly used search filters:
textassigneeprojectsectiontagcompletedis_subtaskdue_ondue_on.beforedue_on.aftermodified_at.beforemodified_at.aftercreated_at.beforecreated_at.after
Create a task
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://app.asana.com/api/1.0/tasks" \
-d '{"data":{"name":"New task","workspace":"WORKSPACE_GID"}}' | jq '.data'
Common task creation fields from the schema:
nameworkspaceassigneeprojectstagsnoteshtml_notesdue_ondue_atstart_onstart_atcustom_fieldsparentfollowers
Update a task
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
-H "Content-Type: application/json" \
-X PUT \
"https://app.asana.com/api/1.0/tasks/TASK_GID" \
-d '{"data":{"name":"Updated task","completed":false}}' | jq '.data'
Subtasks
# List subtasks
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/tasks/TASK_GID/subtasks" | jq '.data'
# Create subtask
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://app.asana.com/api/1.0/tasks/TASK_GID/subtasks" \
-d '{"data":{"name":"Subtask name"}}' | jq '.data'
Stories / comments
In Asana, comments are stories.
Get task stories
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/tasks/TASK_GID/stories" | jq '.data'
Create a comment on a task
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://app.asana.com/api/1.0/tasks/TASK_GID/stories" \
-d '{"data":{"text":"Hello from the API"}}' | jq '.data'
The schema also supports html_text for formatted comments.
Tags and custom fields
List tags in a workspace
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/workspaces/WORKSPACE_GID/tags" | jq '.data'
Get a tag or its tasks
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/tags/TAG_GID" | jq '.data'
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/tags/TAG_GID/tasks" | jq '.data'
List custom fields in a workspace
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/workspaces/WORKSPACE_GID/custom_fields" | jq '.data'
Get custom field settings for a project
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/projects/PROJECT_GID/custom_field_settings" | jq '.data'
Other custom field settings endpoints exist for portfolios, goals, and teams.
Portfolios, goals, statuses
Portfolios
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/portfolios?workspace=WORKSPACE_GID" | jq '.data'
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/portfolios/PORTFOLIO_GID" | jq '.data'
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/portfolios/PORTFOLIO_GID/items" | jq '.data'
Goals
# Filter goals by workspace / team / portfolio / project / task
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/goals?workspace=WORKSPACE_GID" | jq '.data'
# Get goal
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/goals/GOAL_GID" | jq '.data'
Status updates
# parent can be a project, goal, or portfolio
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/status_updates?parent=PARENT_GID" | jq '.data'
Project statuses
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/projects/PROJECT_GID/project_statuses" | jq '.data'
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/project_statuses/PROJECT_STATUS_GID" | jq '.data'
Attachments
List attachments on an object
parent is required and can point to a task, project, or project brief.
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/attachments?parent=TASK_GID" | jq '.data'
Get an attachment
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/attachments/ATTACHMENT_GID" | jq '.data'
Upload an attachment
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
-F "parent=TASK_GID" \
-F "file=@/path/to/file.pdf;type=application/pdf" \
"https://app.asana.com/api/1.0/attachments" | jq '.data'
The attachment API also supports external attachments via resource_subtype=external, parent, name, and url.
Webhooks and events
List webhooks
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/webhooks?workspace=WORKSPACE_GID" | jq '.data'
Optional webhook listing filters include workspace and resource.
Create a webhook
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://app.asana.com/api/1.0/webhooks" \
-d '{"data":{"resource":"PROJECT_GID","target":"https://example.com/asana-webhook"}}' | jq '.data'
The schema also supports webhook filters.
Resource events
Asana's events API is for incremental sync using a sync token.
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/events?resource=PROJECT_GID" | jq .
Then reuse the returned sync token:
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/events?resource=PROJECT_GID&sync=SYNC_TOKEN" | jq .
There is also a workspace-scoped events endpoint:
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/workspaces/WORKSPACE_GID/events" | jq .
Important notes from the official reference:
- Resource events use a
synctoken for incremental updates; if the token is too old, Asana returns412. - Event streams cap a single sync token at 100 events for resources and 1,000 events for workspaces.
Audit log events
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/workspaces/WORKSPACE_GID/audit_log_events" | jq '.data'
Batch API
Batch lets you send multiple requests in one HTTP call.
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://app.asana.com/api/1.0/batch" \
-d '{
"data": {
"actions": [
{
"method": "get",
"relative_path": "/tasks/TASK_GID_1",
"options": {"fields": ["name", "completed"]}
},
{
"method": "get",
"relative_path": "/tasks/TASK_GID_2",
"options": {"fields": ["name", "completed"]}
}
]
}
}' | jq '.data'
Batch action parameters:
relative_pathis relative to/api/1.0and must not contain query parameters.- Place standard parameters in
data, and pagination or output configurations inoptions.
User task lists, time tracking entries, jobs
User task lists
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/user_task_lists/USER_TASK_LIST_GID" | jq '.data'
You can also navigate from a user:
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/users/USER_GID/user_task_list" | jq '.data'
Time tracking entries for a task
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/tasks/TASK_GID/time_tracking_entries" | jq '.data'
Create a time tracking entry for a task
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://app.asana.com/api/1.0/tasks/TASK_GID/time_tracking_entries" \
-d '{"data":{"duration_minutes":30,"description":"API time entry"}}' | jq '.data'
The schema also supports entered_on, attributable_to, billable_status, and categories.
Poll long-running jobs
curl -fsS \
-H "Authorization: Bearer $ASANA_PAT" \
"https://app.asana.com/api/1.0/jobs/JOB_GID" | jq '.data'
Useful for polling asynchronous APIs like exports and larger operations.
Exports
The API includes endpoints such as POST /exports/graph, POST /exports/resource, and POST /organization_exports, which typically return asynchronous jobs that should be polled via job or export endpoints.
Common URL / ID patterns
- In typical resource URLs (
https://app.asana.com/0/PROJECT_GID/TASK_GID), the Task GID is the last path segment and the Project GID is the second-to-last.
echo "https://app.asana.com/0/123456789/9876543210" | sed 's#.*/##'
# => 9876543210
echo "https://app.asana.com/0/123456789/9876543210" | awk -F'/' '{print $(NF-1)}'
# => 123456789
Error handling
| Status | Meaning |
|---|---|
200 |
Success |
201 |
Created |
400 |
Bad request |
401 |
Unauthorized / invalid PAT |
403 |
Forbidden |
404 |
Not found |
412 |
Invalid or expired sync token for events |
429 |
Rate limited |
5xx |
Server error |
Use curl -fsS to fail fast and surface HTTP errors immediately.
Best practices
- Use Bearer authentication: Send
Authorization: Bearer $ASANA_PATon every request. - Wrap JSON writes: Always wrap request payloads in a top-level
dataobject. - Use
opt_fieldsaggressively: Request only the specific fields you need to avoid over-fetching. - Treat
offsetas opaque: Treat pagination offsets as opaque tokens, not numeric indexes. - Default to incomplete tasks unless the user explicitly requests completed ones.
- Use workspace task search when IDs are unknown and you need to find tasks by text or filters.
- Use stories for comments: Task comments are created and retrieved via the
/tasks/{task_gid}/storiesendpoint. - Use jobs for async workflows: Poll the jobs endpoint for asynchronous tasks like exports.
- Prefer events/webhooks over polling to sync data without repeatedly requesting large collections.