The Asana Projects API is a tool that allows users to programmatically interact with Asana projects, enabling them to create, update, and manage tasks and projects within the Asana platform. By leveraging the API, developers can automate workflow processes, integrate Asana with other tools and applications, and access project data in real-time.
openapi: 3.1.0
info:
title: Asana Projects API
description: >-
The Asana Projects API allows users to create, update, and manage projects.
A project represents a prioritized list of tasks in Asana or a board with
columns of tasks represented as cards.
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: Projects
description: Manage projects, memberships, and task organization.
paths:
/projects:
get:
summary: Asana Get multiple projects
description: Returns the compact project records for some filtered set of projects.
operationId: getProjects
tags:
- Projects
parameters:
- name: workspace
in: query
schema:
type: string
- name: team
in: query
schema:
type: string
- name: archived
in: query
schema:
type: boolean
- name: limit
in: query
schema:
type: integer
- name: offset
in: query
schema:
type: string
responses:
'200':
description: Successfully retrieved projects.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ProjectCompact'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'500':
description: Internal server error.
post:
summary: Asana Create a project
description: Creates a new project in a workspace or team.
operationId: createProject
tags:
- Projects
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ProjectRequest'
responses:
'201':
description: Successfully created a new project.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ProjectResponse'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'500':
description: Internal server error.
/projects/{project_gid}:
get:
summary: Asana Get a project
description: Returns the complete project record for a single project.
operationId: getProject
tags:
- Projects
parameters:
- name: project_gid
in: path
required: true
schema:
type: string
example: '12345'
responses:
'200':
description: Successfully retrieved the record for a single project.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ProjectResponse'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
put:
summary: Asana Update a project
description: Updates an existing project.
operationId: updateProject
tags:
- Projects
parameters:
- name: project_gid
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ProjectRequest'
responses:
'200':
description: Successfully updated the project.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ProjectResponse'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
delete:
summary: Asana Delete a project
description: Deletes a project. Tasks in the project are not deleted.
operationId: deleteProject
tags:
- Projects
parameters:
- name: project_gid
in: path
required: true
schema:
type: string
responses:
'200':
description: Successfully deleted the specified project.
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.
/projects/{project_gid}/duplicate:
post:
summary: Asana Duplicate a project
description: Creates a new project by duplicating an existing project asynchronously.
operationId: duplicateProject
tags:
- Projects
parameters:
- name: project_gid
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
name:
type: string
team:
type: string
include:
type: array
items:
type: string
enum:
- members
- notes
- forms
- task_notes
- task_assignee
- task_subtasks
- task_attachments
- task_dates
- task_dependencies
- task_followers
- task_tags
- task_projects
schedule_dates:
type: object
properties:
should_skip_weekends:
type: boolean
due_on:
type: string
format: date
start_on:
type: string
format: date
required:
- name
responses:
'201':
description: Successfully started the duplication job.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
gid:
type: string
resource_type:
type: string
status:
type: string
new_project:
type: object
properties:
gid:
type: string
name:
type: string
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
/projects/{project_gid}/task_counts:
get:
summary: Asana Get task count of a project
description: Returns the task count for a project.
operationId: getTaskCountsForProject
tags:
- Projects
parameters:
- name: project_gid
in: path
required: true
schema:
type: string
responses:
'200':
description: Successfully retrieved the task count.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
num_tasks:
type: integer
num_incomplete_tasks:
type: integer
num_completed_tasks:
type: integer
num_milestones:
type: integer
num_incomplete_milestones:
type: integer
num_completed_milestones:
type: integer
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
/teams/{team_gid}/projects:
get:
summary: Asana Get a team's projects
description: Returns the compact project records for all projects in the team.
operationId: getProjectsForTeam
tags:
- Projects
parameters:
- name: team_gid
in: path
required: true
schema:
type: string
- name: archived
in: query
schema:
type: boolean
- name: limit
in: query
schema:
type: integer
- name: offset
in: query
schema:
type: string
responses:
'200':
description: Successfully retrieved the team's projects.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ProjectCompact'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
post:
summary: Asana Create a project in a team
description: Creates a project shared with the given team.
operationId: createProjectForTeam
tags:
- Projects
parameters:
- name: team_gid
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ProjectRequest'
responses:
'201':
description: Successfully created the specified project.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ProjectResponse'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
/workspaces/{workspace_gid}/projects:
get:
summary: Asana Get all projects in a workspace
description: Returns the compact project records for all projects in the workspace.
operationId: getProjectsForWorkspace
tags:
- Projects
parameters:
- name: workspace_gid
in: path
required: true
schema:
type: string
- name: archived
in: query
schema:
type: boolean
- name: limit
in: query
schema:
type: integer
- name: offset
in: query
schema:
type: string
responses:
'200':
description: Successfully retrieved the workspace's projects.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ProjectCompact'
'400':
description: Bad request.
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Not found.
'500':
description: Internal server error.
post:
summary: Asana Create a project in a workspace
description: Creates a project in the workspace.
operationId: createProjectForWorkspace
tags:
- Projects
parameters:
- name: workspace_gid
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ProjectRequest'
responses:
'201':
description: Successfully created the specified project.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ProjectResponse'
'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:
ProjectCompact:
type: object
properties:
gid:
type: string
readOnly: true
example: '12345'
resource_type:
type: string
readOnly: true
example: project
name:
type: string
example: Stuff to buy
ProjectRequest:
type: object
properties:
name:
type: string
archived:
type: boolean
color:
type: string
nullable: true
default_view:
type: string
enum:
- list
- board
- calendar
- timeline
due_on:
type: string
format: date
nullable: true
notes:
type: string
html_notes:
type: string
owner:
type: string
nullable: true
privacy_setting:
type: string
enum:
- public_to_workspace
- private_to_team
- private
start_on:
type: string
format: date
nullable: true
team:
type: string
workspace:
type: string
ProjectResponse:
type: object
properties:
gid:
type: string
readOnly: true
example: '12345'
resource_type:
type: string
readOnly: true
example: project
name:
type: string
example: Stuff to buy
archived:
type: boolean
color:
type: string
nullable: true
created_at:
type: string
format: date-time
readOnly: true
modified_at:
type: string
format: date-time
readOnly: true
due_on:
type: string
format: date
nullable: true
start_on:
type: string
format: date
nullable: true
default_view:
type: string
enum:
- list
- board
- calendar
- timeline
notes:
type: string
html_notes:
type: string
privacy_setting:
type: string
completed:
type: boolean
readOnly: true
completed_at:
type: string
format: date-time
readOnly: true
nullable: true
owner:
type: object
nullable: true
properties:
gid:
type: string
resource_type:
type: string
name:
type: string
team:
type: object
properties:
gid:
type: string
resource_type:
type: string
name:
type: string
workspace:
type: object
properties:
gid:
type: string
resource_type:
type: string
name:
type: string
members:
type: array
readOnly: true
items:
type: object
properties:
gid:
type: string
resource_type:
type: string
name:
type: string
followers:
type: array
readOnly: true
items:
type: object
properties:
gid:
type: string
resource_type:
type: string
name:
type: string
permalink_url:
type: string
readOnly: true
icon:
type: string
nullable: true