# Asana

> Manage tasks, projects, and comments in Asana with full CRUD operations, search by text, and project listing.

Source: https://cotera.co/docs/reference/tools/individual-tools/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](https://app.asana.com/0/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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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