The Asana Tasks API is a powerful tool that allows developers to programmatically manage tasks and projects within the Asana platform. With this API, users can create, update, and delete tasks, as well as assign tasks to users, set due dates, and track task progress. By integrating the Asana Tasks API into their applications, developers can streamline project management processes, improve communication, and increase productivity within their teams.
openapi: 3.1.0
info:
title: Asana Tasks API
description: >-
The Asana Tasks API is the core API for managing tasks. The task is the
basic object around which many operations in Asana are centered.
version: '1.0'
termsOfService: https://asana.com/terms
contact:
name: Asana Support
url: https://asana.com/support
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://app.asana.com/api/1.0
description: Main endpoint.
security:
- personalAccessToken: []
- oauth2: []
tags:
- name: Tasks
description: Create, update, and manage tasks.
paths:
/tasks:
get:
summary: Asana Get multiple tasks
description: Returns the compact task records for some filtered set of tasks.
operationId: getTasks
tags:
- Tasks
parameters:
- name: project
in: query
schema:
type: string
- name: section
in: query
schema:
type: string
- name: workspace
in: query
schema:
type: string
- name: assignee
in: query
schema:
type: string
- name: completed_since
in: query
schema:
type: string
- name: modified_since
in: query
schema:
type: string
- name: limit
in: query
schema:
type: integer
- name: offset
in: query
schema:
type: string
responses:
'200':
description: Successfully retrieved the requested tasks.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/TaskCompact'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'500':
description: Internal server error.
post:
summary: Asana Create a task
description: Creates a new task.
operationId: createTask
tags:
- Tasks
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/TaskRequest'
responses:
'201':
description: Successfully created a new task.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/TaskResponse'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'500':
description: Internal server error.
/tasks/{task_gid}:
get:
summary: Asana Get a task
description: Returns the complete task record for a single task.
operationId: getTask
tags:
- Tasks
parameters:
- name: task_gid
in: path
required: true
schema:
type: string
example: '321654'
responses:
'200':
description: Successfully retrieved the record for a single task.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/TaskResponse'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
put:
summary: Asana Update a task
description: Updates an existing task.
operationId: updateTask
tags:
- Tasks
parameters:
- name: task_gid
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/TaskRequest'
responses:
'200':
description: Successfully updated the task.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/TaskResponse'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
delete:
summary: Asana Delete a task
description: Deletes a task including all of its subtasks.
operationId: deleteTask
tags:
- Tasks
parameters:
- name: task_gid
in: path
required: true
schema:
type: string
responses:
'200':
description: Successfully deleted the task.
content:
application/json:
schema:
type: object
properties:
data:
type: object
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
/tasks/{task_gid}/subtasks:
get:
summary: Asana Get subtasks from a task
description: Returns a compact representation of all subtasks of a task.
operationId: getSubtasksForTask
tags:
- Tasks
parameters:
- name: task_gid
in: path
required: true
schema:
type: string
- name: limit
in: query
schema:
type: integer
- name: offset
in: query
schema:
type: string
responses:
'200':
description: Successfully retrieved the subtasks.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/TaskCompact'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
post:
summary: Asana Create a subtask
description: Creates a new subtask and adds it to the parent task.
operationId: createSubtaskForTask
tags:
- Tasks
parameters:
- name: task_gid
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/TaskRequest'
responses:
'201':
description: Successfully created the subtask.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/TaskResponse'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
/projects/{project_gid}/tasks:
get:
summary: Asana Get tasks from a project
description: Returns the compact task records for all tasks within the given project.
operationId: getTasksForProject
tags:
- Tasks
parameters:
- name: project_gid
in: path
required: true
schema:
type: string
- name: completed_since
in: query
schema:
type: string
- name: limit
in: query
schema:
type: integer
- name: offset
in: query
schema:
type: string
responses:
'200':
description: Successfully retrieved the requested tasks.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/TaskCompact'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
/workspaces/{workspace_gid}/tasks/search:
get:
summary: Asana Search tasks in a workspace
description: Performs an advanced search for tasks within a workspace.
operationId: searchTasksForWorkspace
tags:
- Tasks
parameters:
- name: workspace_gid
in: path
required: true
schema:
type: string
- name: text
in: query
schema:
type: string
- name: assignee.any
in: query
schema:
type: string
- name: projects.any
in: query
schema:
type: string
- name: tags.any
in: query
schema:
type: string
- name: completed
in: query
schema:
type: boolean
- name: is_subtask
in: query
schema:
type: boolean
- name: sort_by
in: query
schema:
type: string
enum:
- due_date
- created_at
- completed_at
- likes
- modified_at
- name: sort_ascending
in: query
schema:
type: boolean
responses:
'200':
description: Successfully retrieved the requested tasks.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/TaskCompact'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
components:
securitySchemes:
personalAccessToken:
type: http
scheme: bearer
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://app.asana.com/-/oauth_authorize
tokenUrl: https://app.asana.com/-/oauth_token
scopes:
default: Provides access to all endpoints documented in the API reference.
schemas:
TaskCompact:
type: object
properties:
gid:
type: string
readOnly: true
example: '12345'
resource_type:
type: string
readOnly: true
example: task
name:
type: string
example: Buy catnip
resource_subtype:
type: string
enum:
- default_task
- milestone
- section
- approval
example: default_task
TaskRequest:
type: object
properties:
name:
type: string
example: Buy catnip
approval_status:
type: string
enum:
- pending
- approved
- rejected
- changes_requested
completed:
type: boolean
due_at:
type: string
format: date-time
nullable: true
due_on:
type: string
format: date
nullable: true
start_at:
type: string
format: date-time
nullable: true
start_on:
type: string
format: date
nullable: true
notes:
type: string
html_notes:
type: string
assignee:
type: string
nullable: true
assignee_section:
type: string
workspace:
type: string
projects:
type: array
items:
type: string
parent:
type: string
nullable: true
tags:
type: array
items:
type: string
followers:
type: array
items:
type: string
resource_subtype:
type: string
enum:
- default_task
- milestone
- section
- approval
custom_fields:
type: object
additionalProperties: true
TaskResponse:
type: object
properties:
gid:
type: string
readOnly: true
example: '12345'
resource_type:
type: string
readOnly: true
example: task
name:
type: string
example: Buy catnip
resource_subtype:
type: string
approval_status:
type: string
completed:
type: boolean
completed_at:
type: string
format: date-time
readOnly: true
nullable: true
completed_by:
type: object
nullable: true
properties:
gid:
type: string
resource_type:
type: string
name:
type: string
created_at:
type: string
format: date-time
readOnly: true
modified_at:
type: string
format: date-time
readOnly: true
due_at:
type: string
format: date-time
nullable: true
due_on:
type: string
format: date
nullable: true
start_at:
type: string
format: date-time
nullable: true
start_on:
type: string
format: date
nullable: true
notes:
type: string
html_notes:
type: string
assignee:
type: object
nullable: true
properties:
gid:
type: string
resource_type:
type: string
name:
type: string
parent:
type: object
nullable: true
readOnly: true
properties:
gid:
type: string
resource_type:
type: string
name:
type: string
projects:
type: array
readOnly: true
items:
type: object
properties:
gid:
type: string
resource_type:
type: string
name:
type: string
tags:
type: array
readOnly: true
items:
type: object
properties:
gid:
type: string
name:
type: string
followers:
type: array
readOnly: true
items:
type: object
properties:
gid:
type: string
resource_type:
type: string
name:
type: string
workspace:
type: object
readOnly: true
properties:
gid:
type: string
resource_type:
type: string
name:
type: string
custom_fields:
type: array
readOnly: true
items:
type: object
liked:
type: boolean
num_likes:
type: integer
readOnly: true
num_subtasks:
type: integer
readOnly: true
permalink_url:
type: string
readOnly: true
actual_time_minutes:
type: number
readOnly: true
nullable: true