Asana Typeahead API

openapi: 3.2.0
info:
  description: This is the interface for interacting with the Asana Platform. Our API reference is generated from our [OpenAPI spec] (https://raw.githubusercontent.com/Asana/developer-docs/master/defs/asana_oas.yaml).
  x-public-description: This is the interface for interacting with the [Asana Platform](https://developers.asana.com). Our API reference is generated from our [OpenAPI spec] (https://raw.githubusercontent.com/Asana/developer-docs/master/defs/asana_oas.yaml).
  title: Asana Typeahead API
  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
  version: '1.0'
  x-docs-schema-whitelist:
  - AsanaResource
  - AsanaNamedResource
  - AuditLogEvent
  - AttachmentResponse
  - AttachmentCompact
  - BatchResponse
  - CustomFieldSettingResponse
  - CustomFieldSettingCompact
  - CustomFieldResponse
  - CustomFieldCompact
  - EnumOption
  - EventResponse
  - ErrorResponse
  - GoalResponse
  - GoalCompact
  - GoalMembershipCompact
  - GoalMembershipBase
  - GoalMembershipResponse
  - GoalRelationshipResponse
  - GoalRelationshipCompact
  - JobResponse
  - JobCompact
  - OrganizationExportResponse
  - OrganizationExportCompact
  - PortfolioMembershipResponse
  - PortfolioMembershipCompact
  - PortfolioResponse
  - PortfolioCompact
  - ProjectBriefResponse
  - ProjectBriefCompact
  - ProjectMembershipResponse
  - ProjectMembershipCompact
  - ProjectResponse
  - ProjectCompact
  - ProjectStatusResponse
  - ProjectStatusCompact
  - ProjectTemplateCompact
  - ProjectTemplateResponse
  - SectionResponse
  - SectionCompact
  - StatusUpdateResponse
  - StatusUpdateCompact
  - StoryResponse
  - StoryCompact
  - TagResponse
  - TagCompact
  - TaskResponse
  - TaskCompact
  - TaskCountResponse
  - TeamMembershipResponse
  - TeamMembershipCompact
  - TeamResponse
  - TeamCompact
  - TimePeriodResponse
  - TimePeriodCompact
  - UserTaskListResponse
  - UserTaskListCompact
  - UserResponse
  - UserCompact
  - WebhookFilter
  - WebhookResponse
  - WebhookCompact
  - WorkspaceMembershipResponse
  - WorkspaceMembershipCompact
  - WorkspaceResponse
  - WorkspaceCompact
servers:
- url: https://app.asana.com/api/1.0
  description: Main endpoint.
security:
- personalAccessToken: []
- oauth2: []
tags:
- name: Typeahead
  description: The typeahead search API provides search for objects from a single workspace.
paths:
  /workspaces/{workspace_gid}/typeahead:
    parameters:
    - $ref: '#/components/parameters/workspace_path_gid'
    - name: resource_type
      in: query
      description: 'The type of values the typeahead should return. You can choose from one of the following: `custom_field`, `project`, `project_template`, `portfolio`, `tag`, `task`, and `user`. Note that unlike in the names of endpoints, the types listed here are in singular form (e.g. `task`). Using multiple types is not yet supported.'
      required: true
      schema:
        type: string
        enum:
        - custom_field
        - project
        - project_template
        - portfolio
        - tag
        - task
        - user
        default: user
    - name: type
      in: query
      description: '*Deprecated: new integrations should prefer the resource_type field.*'
      required: false
      schema:
        type: string
        enum:
        - custom_field
        - portfolio
        - project
        - tag
        - task
        - user
        default: user
    - name: query
      in: query
      description: The string that will be used to search for relevant objects. If an empty string is passed in, the API will return results.
      schema:
        type: string
      example: Greg
    - name: count
      in: query
      description: The number of results to return. The default is 20 if this parameter is omitted, with a minimum of 1 and a maximum of 100. If there are fewer results found than requested, all will be returned.
      schema:
        type: integer
      example: 20
    - $ref: '#/components/parameters/pretty'
    - $ref: '#/components/parameters/fields'
    get:
      summary: Get objects via typeahead
      description: 'Retrieves objects in the workspace based via an auto-completion/typeahead

        search algorithm. This feature is meant to provide results quickly, so do

        not rely on this API to provide extremely accurate search results. The

        result set is limited to a single page of results with a maximum size, so

        you won’t be able to fetch large numbers of results.


        The typeahead search API provides search for objects from a single

        workspace. This endpoint should be used to query for objects when

        creating an auto-completion/typeahead search feature. This API is meant

        to provide results quickly and should not be relied upon for accurate or

        exhaustive search results. The results sets are limited in size and

        cannot be paginated.


        Queries return a compact representation of each object which is typically

        the gid and name fields. Interested in a specific set of fields or all of

        the fields?! Of course you are. Use field selectors to manipulate what

        data is included in a response.


        Resources with type `user` are returned in order of most contacted to

        least contacted. This is determined by task assignments, adding the user

        to projects, and adding the user as a follower to tasks, messages,

        etc.


        Resources with type `project` are returned in order of recency. This is

        determined when the user visits the project, is added to the project, and

        completes tasks in the project.


        Resources with type `task` are returned with priority placed on tasks

        the user is following, but no guarantee on the order of those tasks.


        Resources with type `project_template` are returned with priority

        placed on favorited project templates.


        Leaving the `query` string empty or omitted will give you results, still

        following the resource ordering above. This could be used to list users or

        projects that are relevant for the requesting user''s api token.'
      tags:
      - Typeahead
      operationId: typeaheadForWorkspace
      responses:
        200:
          description: Successfully retrieved objects via a typeahead search algorithm.
          content:
            application/json:
              schema:
                type: object
                description: A generic list of objects, such as those returned by the typeahead search endpoint.
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AsanaNamedResource'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
          readOnly: true
          description: Message providing more detail about the error that occurred, if available.
          example: 'project: Missing input'
        help:
          type: string
          readOnly: true
          description: Additional information directing developers to resources on how to address and fix the problem, if available.
          example: 'For more information on API status codes and how to handle them, read the docs on errors: https://asana.github.io/developer-docs/#errors'''
        phrase:
          type: string
          readOnly: true
          description: '*500 errors only*. A unique error phrase which can be used when contacting developer support to help identify the exact occurrence of the problem in Asana’s logs.'
          example: 6 sad squid snuggle softly
    AsanaResource:
      description: A generic Asana Resource, containing a globally unique identifier.
      type: object
      properties:
        gid:
          description: Globally unique identifier of the resource, as a string.
          type: string
          readOnly: true
          example: '12345'
          x-insert-after: false
        resource_type:
          description: The base type of this resource.
          type: string
          readOnly: true
          example: task
          x-insert-after: gid
    AsanaNamedResource:
      allOf:
      - $ref: '#/components/schemas/AsanaResource'
      - type: object
        properties:
          name:
            description: The name of the object.
            type: string
            example: Bug Task
    ErrorResponse:
      description: 'Sadly, sometimes requests to the API are not successful. Failures can

        occur for a wide range of reasons. In all cases, the API should return

        an HTTP Status Code that indicates the nature of the failure,

        with a response body in JSON format containing additional information.



        In the event of a server error the response body will contain an error

        phrase. These phrases are automatically generated using the

        [node-asana-phrase

        library](https://github.com/Asana/node-asana-phrase) and can be used by

        Asana support to quickly look up the incident that caused the server

        error.'
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
  responses:
    Forbidden:
      description: The authentication and request syntax was valid but the server is refusing to complete the request. This can happen if you try to read or write to objects or properties that the user does not have access to.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Either the request method and path supplied do not specify a known action in the API, or the object specified by the request does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: A valid authentication token was not provided with the request, so the API could not associate a user with the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  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
    fields:
      name: opt_fields
      in: query
      description: 'Defines fields to return.

        Some requests return *compact* representations of objects in order to conserve resources and complete the request more efficiently. Other times requests return more information than you may need. This option allows you to list the exact set of fields that the API should be sure to return for the objects. The field names should be provided as paths, described below.

        The id of included objects will always be returned, regardless of the field options.'
      example:
      - followers
      - assignee
      required: false
      schema:
        type: array
        items:
          type: string
      style: form
      explode: false
    workspace_path_gid:
      name: workspace_gid
      in: path
      description: Globally unique identifier for the workspace or organization.
      required: true
      schema:
        type: string
      example: '12345'
      x-env-variable: workspace
  securitySchemes:
    personalAccessToken:
      type: http
      description: A personal access token allows access to the api for the user who created it. This should be kept a secret and be treated like a password.
      scheme: bearer
    oauth2:
      type: oauth2
      description: 'We require that applications designed to access the Asana API on behalf of multiple users implement OAuth 2.0.

        Asana supports the Authorization Code Grant flow.'
      flows:
        authorizationCode:
          authorizationUrl: https://app.asana.com/-/oauth_authorize
          tokenUrl: https://app.asana.com/-/oauth_token
          refreshUrl: https://app.asana.com/-/oauth_token
          scopes:
            default: Provides access to all endpoints documented in our API reference. If no scopes are requested, this scope is assumed by default.
            openid: Provides access to OpenID Connect ID tokens and the OpenID Connect user info endpoint.
            email: Provides access to the user’s email through the OpenID Connect user info endpoint.
            profile: Provides access to the user’s name and profile photo through the OpenID Connect user info endpoint.
x-readme:
  proxy-enabled: false
x-provenance:
  method: harvested
  publisher: Asana
  source: https://raw.githubusercontent.com/Asana/developer-docs/master/defs/asana_oas.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)