openapi: 3.1.0
info:
  title: Asana Events API
  description: >-
    The Asana Events API allows users to track changes to resources using event
    subscriptions. Events are delivered within a minute on average, designed for
    at-most-once delivery, and are retrievable from the event stream for 24 hours.
  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: Events
    description: Track changes to Asana resources via event subscriptions.
paths:
  /events:
    get:
      summary: Asana Get events on a resource
      description: >-
        Returns the full record for all events that have occurred since the sync
        token was created. A GET request to the endpoint with no sync token will
        return a 412 error providing a new sync token.
      operationId: getEvents
      tags:
        - Events
      parameters:
        - name: resource
          in: query
          required: true
          description: A resource ID to subscribe to.
          schema:
            type: string
          example: '12345'
        - name: sync
          in: query
          required: false
          description: A sync token received from the last request, or none on first request.
          schema:
            type: string
        - name: opt_fields
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: false
      responses:
        '200':
          description: Successfully retrieved events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EventResponse'
                  sync:
                    type: string
                    description: A sync token to use in the next request.
                  has_more:
                    type: boolean
                    description: Whether there are more events to retrieve.
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
        '404':
          description: Not found.
        '412':
          description: >-
            Sync token invalid or expired. The response will include a new sync token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sync:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
        '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:
    EventResponse:
      type: object
      description: An event representing a change to a resource.
      properties:
        user:
          type: object
          description: The user who triggered the event.
          properties:
            gid:
              type: string
            resource_type:
              type: string
            name:
              type: string
        resource:
          type: object
          description: The resource that triggered the event.
          properties:
            gid:
              type: string
            resource_type:
              type: string
            name:
              type: string
        type:
          type: string
          readOnly: true
          description: Deprecated. Refer to the resource_type of the resource.
          example: task
        action:
          type: string
          readOnly: true
          description: >-
            The type of action taken on the resource. One of changed, added,
            removed, deleted, or undeleted.
          enum:
            - changed
            - added
            - removed
            - deleted
            - undeleted
          example: changed
        parent:
          type: object
          nullable: true
          description: For added/removed events, the parent object.
          properties:
            gid:
              type: string
            resource_type:
              type: string
            name:
              type: string
        created_at:
          type: string
          format: date-time
          readOnly: true
          example: '2012-02-22T02:06:58.147Z'
        change:
          type: object
          readOnly: true
          description: Information about the type of change. Only present when action is changed.
          properties:
            field:
              type: string
              description: The name of the field that changed.
              example: assignee
            action:
              type: string
              description: The type of action on the field.
              enum:
                - changed
                - added
                - removed
              example: changed
            new_value:
              type: object
              description: The new value of the field, if an Asana resource.
              properties:
                gid:
                  type: string
                resource_type:
                  type: string
            added_value:
              type: object
              description: The added value, if the field change action is added.
              properties:
                gid:
                  type: string
                resource_type:
                  type: string
            removed_value:
              type: object
              description: The removed value, if the field change action is removed.
              properties:
                gid:
                  type: string
                resource_type:
                  type: string