Zendesk Search API

openapi: 3.2.0
info:
  version: '1.0'
  title: Zendesk Search API
  description: Needs a description.
tags:
- name: Search
paths:
  /api/v2/search:
    get:
      operationId: ListSearchResults
      tags:
      - Search
      summary: Zendesk Get Api V2 Search
      description: 'Returns the search results. See Query basics for the syntax of the `query` parameter.


        Use the ampersand character (&) to append the `sort_by` or `sort_order` parameters to the URL.


        For examples, see Searching with Zendesk API.


        #### Allowed For


        * Agents


        #### Pagination


        * Offset pagination only


        Offset pagination may result in duplicate results when paging. You can also use the

        Export Search Results endpoint, which

        uses cursor-based pagination and doesn''t return duplicate results. See

        Using cursor pagination for more information.


        #### Errors JSON Format


        Errors are represented as JSON objects which have the following keys:


        | Name | Type | Comment

        | --------------------- | ---------------------| --------------------

        | error | string | The type of error. Examples: "unavailable", "invalid"

        | description | string |


        ##### Example Error

        ```js

        {

        "error": "unavailable",

        "description": "Sorry, we could not complete your search query. Please try again in a moment."

        }

        ```'
      parameters:
      - name: query
        in: query
        description: The search query. See [Query basics](#query-basics) above. For details on the query syntax, see the [Zendesk Support search reference](https://support.zendesk.com/hc/en-us/articles/203663226)
        required: true
        schema:
          type: string
        example: https://subdomain.zendesk.com/api/v2/search.json?query=type:ticket status:closed&sort_by=status&sort_order=desc
      - name: sort_by
        in: query
        description: One of `updated_at`, `created_at`, `priority`, `status`, or `ticket_type`. Defaults to sorting by relevance
        schema:
          type: string
      - name: sort_order
        in: query
        description: One of `asc` or `desc`.  Defaults to `desc`
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              examples:
                default:
                  $ref: '#/components/examples/SearchResponseExample'
  /api/v2/search/count:
    get:
      operationId: CountSearchResults
      tags:
      - Search
      summary: Zendesk Get Api V2 Search Count
      description: 'Returns the number of items matching the query rather than the items. The search string works the same as a regular search.


        #### Allowed For


        - Agents'
      parameters:
      - name: query
        in: query
        description: The search query
        required: true
        schema:
          type: string
        example: https://subdomain.zendesk.com/api/v2/search.json?query=type:ticket status:closed
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCountResponse'
              examples:
                default:
                  $ref: '#/components/examples/SearchCountResponseExample'
  /api/v2/search/export:
    get:
      operationId: ExportSearchResults
      tags:
      - Search
      summary: Zendesk Get Api V2 Search Export
      description: 'Exports a set of results. See Query syntax for the syntax of the `query` parameter.


        Use this endpoint for search queries that will return more than 1000 results. The result set is ordered only by the `created_at` attribute.


        The search only returns results of a single object type. The following object types are supported: ticket, organization, user, or group.


        You must specify the type in the `filter[type]` parameter. Searches with type in the query string will result in an error.


        #### Allowed For


        - Agents


        #### Pagination


        - Cursor pagination


        See Pagination.


        Returns a maximum of 1000 records per page. The number of results shown in a page is determined by the `page[size]` parameter.


        **Note**: You may experience a speed reduction or a timeout if you request 1000 results per page and you have many archived tickets in the results. Try reducing the number of results per page. We recommend 100 results per page.


        The cursor specified by the `after_cursor` property in a response expires after one hour.


        For more information on cursor-based pagination, see the following articles:


        - Comparing cursor pagination and offset pagination

        - Paginating through lists using cursor pagination


        #### Limits


        This API endpoint is rate-limited to 100 requests per minute per account. The limit also counts towards the global API rate limit.


        #### Response Format


        | Name | Type | Comment

        | --------------------- | ---------------------| --------------------

        | links[next] | string | URL to the next page of results

        | meta[has_more] | string | Boolean indicating if there are more results

        | meta[after_cursor] | string | Cursor object returned from the Search Service

        | results | array | May consist of tickets, users, groups, or organizations, as specified by the `filter_type` parameter


        The response is similar to the response of `GET /api/v2/search.json?`, with a few changes:


        * `links` - Has the following nested properties: `prev` and `next`. These replace the `next_page` and `prev_page` links. The `prev` property is always null because backward pagination is not supported. The `next` property may include an auto-generated link to the next page of results.

        * `meta` - Has the following nested properties: `has_more` and `after_cursor`. The `has_more` property indicates whether the next page has more results. The `after_cursor` property is the cursor used to paginate to the next page. It expires after one hour.


        There''s no `count` property.'
      parameters:
      - name: query
        in: query
        description: The search query. See [Query basics](#query-basics) above. For details on the query syntax, see the [Zendesk Support search reference](https://support.zendesk.com/hc/en-us/articles/203663226)
        required: true
        schema:
          type: string
        example: https://subdomain.zendesk.com/api/v2/search.json?query=type:ticket status:closed&sort_by=status&sort_order=desc
      - name: page[size]
        in: query
        description: The number of results shown in a page.
        schema:
          type: integer
      - name: filter[type]
        in: query
        description: The object type returned by the export query. Can be `ticket`, `organization`, `user`, or `group`.
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchExportResponse'
              examples:
                default:
                  $ref: '#/components/examples/SearchExportResponseExample'
components:
  schemas:
    SearchCountResponse:
      type: object
      properties:
        count:
          type: integer
    SearchExportResponse:
      type: object
      properties:
        facets:
          type: string
          description: The facets corresponding to the search query
          nullable: true
          readOnly: true
        links:
          type: object
          description: The links to the previous and next entries via the cursor ids in the metadata.
          properties:
            next:
              type: string
              description: The url to the next entry via the cursor.
              nullable: true
              readOnly: true
            prev:
              type: string
              description: The url to the previous entry via the cursor.
              nullable: true
              readOnly: true
        meta:
          type: object
          description: Metadata for the export query response.
          properties:
            after_cursor:
              type: string
              description: The cursor id for the next object.
              nullable: true
              readOnly: true
            before_cursor:
              type: string
              description: The cursor id for the previous object.
              nullable: true
              readOnly: true
            has_more:
              type: boolean
              description: Whether there are more items yet to be returned by the cursor.
              readOnly: true
        results:
          type: array
          description: May consist of tickets, users, groups, or organizations, as specified by the `result_type` property in each result object
          items:
            $ref: '#/components/schemas/SearchResultObject'
          readOnly: true
      example:
        facets: null
        links:
          next: https://example.zendesk.com/api/v2/search/export.json?filter%5Btype%5D=ticket&page%5Bafter%5D=eyJmaWVsZCI6ImNyZWF0ZWRfYXQiLCJkZXNjIjp0cnVlLCJ0aWVCcmVha0ZpZWxkIjoiaWQiLCJ0aWVCcmVha0Rlc2MiOmZhbHNlLCJzb3J0VmFsdWVzIjpudWxsLCJleHBvcnRlZFRodXNGYXIiOjAsInNlc3Npb25TdGFydCI6MTYwNzAzOTI1Mzk4NSwiY3JlYXRlZEF0IjoxNjA3MDM5MjUzOTg1LCJzYWx0ZWRSZXF1ZXN0SGFzaCI6LTQ5ODM0ODc3LCJzYWx0ZWRDdXJzb3JIYXNoIjotMjQwMzQ4MjgwfQ%3D%3D&page%5Bsize%5D=100&query=hello%26page%5Bsize%5D%3D100%26filter%5Btype%5D%3Dticket
          prev: null
        meta:
          after_cursor: eyJmaWVsZCI6ImNyZWF0ZWRfYXQiLCJkZXNjIjp0cnVlLCJ0aWVCcmVha0ZpZWxkIjoiaWQiLCJ0aWVCcmVha0Rlc2MiOmZhbHNlLCJzb3J0VmFsdWVzIjpudWxsLCJleHBvcnRlZFRodXNGYXIiOjAsInNlc3Npb25TdGFydCI6MTYwNzAzOTI1Mzk4NSwiY3JlYXRlZEF0IjoxNjA3MDM5MjUzOTg1LCJzYWx0ZWRSZXF1ZXN0SGFzaCI6LTQ5ODM0ODc3LCJzYWx0ZWRDdXJzb3JIYXNoIjotMjQwMzQ4MjgwfQ==
          before_cursor: null
          has_more: true
        results: []
    SearchResponse:
      type: object
      properties:
        count:
          type: integer
          description: The number of resources returned by the query corresponding to this page of results in the paginated response
          readOnly: true
        facets:
          type: string
          description: The facets corresponding to the search query
          nullable: true
          readOnly: true
        next_page:
          type: string
          description: URL to the next page of results
          nullable: true
          readOnly: true
        previous_page:
          type: string
          description: URL to the previous page of results
          nullable: true
          readOnly: true
        results:
          type: array
          description: May consist of tickets, users, groups, or organizations, as specified by the `result_type` property in each result object
          items:
            $ref: '#/components/schemas/SearchResultObject'
          readOnly: true
      example:
        count: 1
        facets: null
        next_page: null
        previous_page: null
        results:
        - created_at: '2018-04-06T03:17:05Z'
          default: false
          deleted: false
          description: ''
          id: 1835972
          name: Ragtail
          result_type: group
          updated_at: '2018-04-06T03:17:05Z'
          url: https://example.zendesk.com/api/v2/groups/1835972.json