cotera
Logo

Asana

Authentication Type: Bearer Token Description: Manage tasks, projects, and comments in Asana with full CRUD operations, search by text, and project listing.

Authentication

To authenticate with Asana, you'll need a Personal Access Token:

  1. Go to the Asana Developer Console
  2. Click Create new token and give it a descriptive name
  3. Copy the token value

You'll need to provide:

  • apiKey string: Your Asana Personal Access Token

Security tip: Personal Access Tokens grant access to all workspaces and organizations your Asana account belongs to. Keep your token secure and rotate it periodically. If you only need read access, consider creating a token on a restricted account.

Tasks

Create Task

Create a new task in an Asana workspace. You can optionally assign it to a user, set a due date, add notes, and attach it to one or more projects.

Operation Type: Mutation (Write)

Parameters:

  • workspace string (required): The GID of the workspace to create the task in
  • name string (required): The name of the task
  • assignee string (nullable): The GID of the user to assign the task to (e.g., 1234567890)
  • due_on string (nullable): The due date of the task in YYYY-MM-DD format
  • notes string (nullable): Plain-text description of the task
  • projects array of strings (nullable): List of project GIDs to add the task to

Returns:

  • gid string: The globally unique identifier for the task
  • name string: The name of the task
  • assignee object (nullable): The assigned user
  • due_on string (nullable): The due date of the task
  • notes string: Plain-text notes on the task
  • completed boolean: Whether the task is completed
  • permalink_url string: A URL to the task in Asana
  • created_at string: ISO 8601 timestamp of when the task was created

Example Usage:

{
  "workspace": "1234567890",
  "name": "Review Q2 marketing plan",
  "assignee": "9876543210",
  "due_on": "2025-04-15",
  "notes": "Please review the attached deck and leave comments by EOD Friday.",
  "projects": ["1111111111", "2222222222"]
}

Get Task

Retrieve a single task by its GID, including full details such as projects, tags, and custom fields.

Operation Type: Query (Read)

Parameters:

  • taskGid string (required): The GID of the task to retrieve

Returns:

  • gid string: The globally unique identifier for the task
  • name string: The name of the task
  • assignee object (nullable): The assigned user
  • due_on string (nullable): The due date of the task
  • notes string: Plain-text notes on the task
  • completed boolean: Whether the task is completed
  • completed_at string (nullable): ISO 8601 timestamp of when the task was completed
  • permalink_url string: A URL to the task in Asana
  • created_at string: ISO 8601 timestamp of when the task was created
  • modified_at string: ISO 8601 timestamp of when the task was last modified
  • projects array of objects: Projects the task belongs to
  • tags array of objects: Tags applied to the task
  • custom_fields array of objects: Custom field values on the task

Example Usage:

{
  "taskGid": "1205673456789"
}

List Tasks

List tasks filtered by project, assignee, or workspace. You can also filter by completion date and control the number of results.

Operation Type: Query (Read)

Parameters:

  • project string (nullable): The GID of a project to list tasks from
  • assignee string (nullable): The GID of a user whose tasks to list. Requires workspace to also be set.
  • workspace string (nullable): The GID of the workspace to scope the query to. Required when filtering by assignee.
  • completed_since string (nullable): ISO 8601 datetime. Only return tasks completed after this time. Use now to return only incomplete tasks.
  • limit number (nullable): Maximum number of tasks to return (default 100)

Returns:

  • array of objects: List of tasks matching the filters
    • gid string: The task GID
    • name string: The task name
    • assignee object (nullable): The assigned user
    • due_on string (nullable): The due date
    • completed boolean: Whether the task is completed
    • permalink_url string: A URL to the task in Asana

Example Usage:

{
  "project": "1111111111",
  "completed_since": "now",
  "limit": 50
}

Search Tasks

Search for tasks in a workspace by text, with optional filtering by completion status.

Operation Type: Query (Read)

Parameters:

  • workspaceGid string (required): The GID of the workspace to search in
  • text string (required): The text to search for in task names and descriptions
  • completed boolean (nullable): If set, filter to only completed (true) or incomplete (false) tasks
  • limit number (nullable): Maximum number of tasks to return

Returns:

  • array of objects: List of tasks matching the search criteria
    • gid string: The task GID
    • name string: The task name
    • assignee object (nullable): The assigned user
    • due_on string (nullable): The due date
    • completed boolean: Whether the task is completed
    • permalink_url string: A URL to the task in Asana

Example Usage:

{
  "workspaceGid": "1234567890",
  "text": "launch checklist",
  "completed": false,
  "limit": 25
}

Update Task

Update an existing task. Only the fields you specify will be changed; other fields remain unchanged.

Operation Type: Mutation (Write)

Parameters:

  • taskGid string (required): The GID of the task to update
  • name string (nullable): New name for the task
  • assignee string (nullable): GID of the user to reassign the task to
  • due_on string (nullable): New due date in YYYY-MM-DD format
  • notes string (nullable): New plain-text notes for the task
  • completed boolean (nullable): Set to true to mark the task as complete, or false to reopen it

Returns:

  • gid string: The task GID
  • name string: The updated task name
  • assignee object (nullable): The assigned user
  • due_on string (nullable): The due date
  • notes string: The task notes
  • completed boolean: Whether the task is completed
  • permalink_url string: A URL to the task in Asana

Example Usage:

{
  "taskGid": "1205673456789",
  "completed": true,
  "notes": "Completed after final review. No further action needed."
}

Add Comment

Add a text comment (story) to a task. Optionally pin the comment to the top of the task's conversation.

Operation Type: Mutation (Write)

Parameters:

  • taskGid string (required): The GID of the task to comment on
  • text string (required): The plain-text body of the comment
  • isPinned boolean (nullable): If true, the comment will be pinned to the top of the task's conversation

Returns:

  • gid string: The globally unique identifier for the comment
  • text string: The text content of the comment
  • created_at string: ISO 8601 timestamp of when the comment was created
  • created_by object: The user who created the comment

Example Usage:

{
  "taskGid": "1205673456789",
  "text": "Heads up -- the design assets are now uploaded to the shared drive.",
  "isPinned": false
}

Projects

List Projects

List all projects in a workspace, with optional filtering by archived status.

Operation Type: Query (Read)

Parameters:

  • workspaceGid string (required): The GID of the workspace to list projects from
  • archived boolean (nullable): If true, return only archived projects. If false, return only active projects. If omitted, return all projects.
  • limit number (nullable): Maximum number of projects to return

Returns:

  • array of objects: List of projects
    • gid string: The project GID
    • name string: The project name
    • archived boolean: Whether the project is archived
    • color string (nullable): The project color
    • created_at string: ISO 8601 timestamp of when the project was created
    • permalink_url string: A URL to the project in Asana

Example Usage:

{
  "workspaceGid": "1234567890",
  "archived": false,
  "limit": 20
}

Common Use Cases

Project Management:

  • Track tasks across multiple projects and workspaces
  • Update task statuses, due dates, and assignees as work progresses
  • List incomplete tasks for a project to generate sprint reports or standups
  • Move tasks between projects by updating project memberships

Sprint & Status Automation:

  • Pull all tasks assigned to a user for daily standups or weekly reports
  • Search for overdue or at-risk tasks using text search and completion filters
  • Mark tasks complete programmatically when related events occur in other systems
  • Generate project summaries by listing tasks and aggregating their statuses

Team Communication:

  • Add comments to tasks when updates come in from Slack, email, or other channels
  • Pin important status updates to keep key information visible on tasks
  • Search for tasks mentioned in conversations and link back to them

Cross-Tool Workflows:

  • Sync Asana tasks with CRM deals, support tickets, or calendar events
  • Create Asana tasks automatically when issues are filed in other tools
  • Update Asana when deployments, releases, or approvals happen elsewhere
  • List projects to discover workspace structure before building integrations