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