openapi: 3.0.2
info:
  title: Query Suggestions API
  summary: The Query Suggestions API lets you manage your Query Suggestions configurations
  description: |
    Query Suggestions add new indices to your Algolia application with popular search queries, external suggestions, or facet values.
    In your user interface, you can query the Query Suggestions indices like regular indices and add [suggested searches](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/js) to guide users and speed up their search.

    ## Base URLs

    Base URLs for the Query Suggestions API:

    - `https://query-suggestions.us.algolia.com`
    - `https://query-suggestions.eu.algolia.com`

    Use the URL that matches your [analytics region](https://dashboard.algolia.com/account/infrastructure/analytics).

    **All requests must use HTTPS.**

    ## Authentication

    Add these headers to authenticate requests:

    - `x-algolia-application-id`. Your Algolia application ID.
    - `x-algolia-api-key`. An API key with the necessary permissions to make the request.
      The required access control list (ACL) to make a request is listed in each endpoint's reference.

    You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys).

    ## Request format

    Request bodies must be JSON objects.

    ## Response status and errors

    Response bodies are JSON objects.
    Deleting a user token returns an empty response body with rate-limiting information as headers.

    Successful responses return `2xx` statuses. Client errors return `4xx` statuses. Server errors return `5xx` statuses.
    Error responses have a `message` property with more information.

    ## Version

    The current version of the Query Suggestions API is version 1, indicated by the `/1/` in each endpoint's URL.
  version: 1.0.0
components:
  securitySchemes:
    appId:
      $ref: '../common/securitySchemes.yml#/appId'
    apiKey:
      $ref: '../common/securitySchemes.yml#/apiKey'
servers:
  - url: https://query-suggestions.{region}.algolia.com
    description: |
      You can check the region for your application in the [Algolia dashboard](https://dashboard.algolia.com/account/infrastructure/analytics).
      If you connect to the wrong region, the API returns an error with the status `401` and the message: "The log processing region does not match".
    variables:
      region:
        description: The region where your Algolia application is hosted.
        enum:
          - us
          - eu
        default: us
security:
  - appId: []
    apiKey: []
tags:
  - name: configurations
    x-displayName: Configurations
    description: Manage Query Suggestions configurations.
  - name: logs
    x-displayName: Logs
    description: Get logs for a Query Suggestions index.
x-tagGroups:
  - name: Configurations
    tags:
      - configurations
  - name: Logs
    tags:
      - logs
paths:
  # ######################
  # ### Custom request ###
  # ######################
  /{path}:
    $ref: '../common/paths/customRequest.yml'

  /1/configs:
    $ref: 'paths/qsConfigs.yml'
  /1/configs/{indexName}:
    $ref: 'paths/qsConfig.yml'
  /1/configs/{indexName}/status:
    $ref: 'paths/getConfigurationStatus.yml'
  /1/logs/{indexName}:
    $ref: 'paths/getLogFile.yml'

  # ###############
  # ### Helpers ###
  # ###############
  /setClientApiKey:
    $ref: '../common/helpers/setClientApiKey.yml#/method'