Asana Events API

openapi: 3.1.0
info:
  title: Asana Allocations Events API
  description: The Asana Allocations API allows users to manage and allocate resources within their Asana project management system. An allocation object represents how much of a resource (e.g. person, team) is dedicated to a specific work object (e.g. project, portfolio) over a specific period of time. The effort value can be a percentage or number of 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:
    parameters:
    - name: resource
      in: query
      required: true
      description: A resource ID to subscribe to. The resource can be a task, project, or goal.
      schema:
        type: string
      example: '12345'
    - name: sync
      in: query
      required: false
      description: 'A sync token received from the last request, or none on first sync. Events will be returned from the point in time that the sync token was generated.

        *Note: On your first request, omit the sync token. The response will be the same as for an expired sync token, and will include a new valid sync token.If the sync token is too old (which may happen from time to time) the API will return a `412 Precondition Failed` error, and include a fresh sync token in the response.*'
      schema:
        type: string
      example: de4774f6915eae04714ca93bb2f5ee81
    - $ref: '#/components/parameters/pretty'
    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:
  parameters:
    pretty:
      name: opt_pretty
      in: query
      description: 'Provides “pretty” output.

        Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.'
      required: false
      allowEmptyValue: true
      schema:
        type: boolean
      style: form
      example: true
  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
  securitySchemes:
    personalAccessToken:
      type: http
      description: A personal access token for the Asana API.
      scheme: bearer
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization code flow.
      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.