openapi: 3.0.2
info:
  title: Algolia Query Suggestions API
  description: >-
    The Algolia Query Suggestions API is a powerful tool that allows developers
    to enhance search functionality on their websites or applications. By
    utilizing advanced algorithms, the API generates real-time suggestions as
    users type in the search bar, helping them quickly find relevant content or
    products. These suggestions are based on popular search queries, user
    behavior, and contextual relevance, improving search accuracy and user
    experience. Additionally, the API offers customization options, such as the
    ability to prioritize certain suggestions or filter out irrelevant results.
    Overall, the Algolia Query Suggestions API streamlines the search process,
    leading to increased user engagement and satisfaction.
  version: 1.0.0
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:
        enum:
          - us
          - eu
        default: us
security:
  - appId: []
    apiKey: []
tags:
  - name: Query-Suggestions
paths:
  /{path}:
    get:
      operationId: customGet
      summary: Send requests to the Algolia REST API
      description: This method allow you to send requests to the Algolia REST API.
      parameters:
        - $ref: '#/components/parameters/PathInPath'
        - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      tags:
        - Query-Suggestions
    post:
      operationId: customPost
      requestBody:
        description: Parameters to send with the custom request.
        content:
          application/json:
            schema:
              type: object
      summary: Send requests to the Algolia REST API
      description: This method allow you to send requests to the Algolia REST API.
      parameters:
        - $ref: '#/components/parameters/PathInPath'
        - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      tags:
        - Query-Suggestions
    put:
      operationId: customPut
      requestBody:
        description: Parameters to send with the custom request.
        content:
          application/json:
            schema:
              type: object
      summary: Send requests to the Algolia REST API
      description: This method allow you to send requests to the Algolia REST API.
      parameters:
        - $ref: '#/components/parameters/PathInPath'
        - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      tags:
        - Query-Suggestions
    delete:
      operationId: customDelete
      summary: Send requests to the Algolia REST API
      description: This method allow you to send requests to the Algolia REST API.
      parameters:
        - $ref: '#/components/parameters/PathInPath'
        - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      tags:
        - Query-Suggestions
  /1/configs:
    get:
      tags:
        - Query-Suggestions
      operationId: getAllConfigs
      x-acl:
        - settings
      summary: Algolia List configurations
      description: >-
        Retrieves all Query Suggestions configurations of your Algolia
        application.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConfigurationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
        - Query-Suggestions
      operationId: createConfig
      x-acl:
        - editSettings
      summary: Algolia Create a configuration
      description: |
        Creates a new Query Suggestions configuration.

        You can have up to 100 configurations per Algolia application.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigurationWithIndex'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              examples:
                Created:
                  summary: Configuration created
                  value:
                    status: 200
                    message: >-
                      Configuration was created, and a new indexing job has been
                      scheduled.
        '400':
          $ref: '#/components/responses/BadRequest-2'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /1/configs/{indexName}:
    get:
      tags:
        - Query-Suggestions
      operationId: getConfig
      x-acl:
        - settings
      summary: Algolia Retrieve a configuration
      description: Retrieves a single Query Suggestions configuration by its index name.
      parameters:
        - $ref: '#/components/parameters/IndexName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigurationResponse'
        '400':
          $ref: '#/components/responses/BadRequest-2'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - Query-Suggestions
      operationId: updateConfig
      x-acl:
        - editSettings
      summary: Algolia Update a configuration
      description: Updates a QuerySuggestions configuration.
      parameters:
        - $ref: '#/components/parameters/IndexName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Configuration'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              examples:
                Created:
                  summary: Configuration created
                  value:
                    status: 200
                    message: >-
                      Configuration was updated, and a new indexing job has been
                      scheduled.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError-2'
    delete:
      tags:
        - Query-Suggestions
      operationId: deleteConfig
      x-acl:
        - editSettings
      summary: Algolia Delete a configuration
      description: >
        Deletes a Query Suggestions configuration.


        Deleting only removes the configuration and stops updates to the Query
        Suggestions index.

        To delete the Query Suggestions index itself, use the Search API and the
        `Delete an index` operation.
      parameters:
        - $ref: '#/components/parameters/IndexName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              examples:
                Created:
                  summary: Configuration created
                  value:
                    status: 200
                    message: Configuration was deleted with success.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError-2'
  /1/configs/{indexName}/status:
    get:
      tags:
        - Query-Suggestions
      operationId: getConfigStatus
      x-acl:
        - settings
      summary: Algolia Retrieve configuration status
      description: Reports the status of a Query Suggestions index.
      parameters:
        - $ref: '#/components/parameters/IndexName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: configStatus
                type: object
                additionalProperties: false
                properties:
                  indexName:
                    $ref: '#/components/schemas/IndexName'
                  isRunning:
                    type: boolean
                    description: >-
                      Whether the creation or update of the Query Suggestions
                      index is in progress.
                    example: false
                  lastBuiltAt:
                    type: string
                    description: >-
                      Date and time when the Query Suggestions index was last
                      built, in RFC 3339 format.
                    example: '2023-07-05T08:03:53Z'
                  lastSuccessfulBuiltAt:
                    type: string
                    description: >-
                      Date and time when the Query Suggestions index was last
                      updated successfully.
                    example: '2023-07-05T08:03:53Z'
                  lastSuccessfulBuildDuration:
                    type: string
                    description: Duration of the last successful build in seconds.
                    example: 28
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /1/logs/{indexName}:
    get:
      tags:
        - Query-Suggestions
      operationId: getLogFile
      x-acl:
        - settings
      summary: Algolia Retrieve logs
      description: Retrieves the logs for a single Query Suggestions index.
      parameters:
        - $ref: '#/components/parameters/IndexName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: logFile
                type: object
                additionalProperties: false
                properties:
                  timestamp:
                    type: string
                    description: Date and time of the log entry, in RFC 3339 format.
                    example: '2023-07-05T08:03:33.898076171Z'
                  level:
                    $ref: '#/components/schemas/LogLevel'
                  message:
                    type: string
                    description: Details about this log entry.
                    example: >-
                      skipping query "Brooke Adams": not enough search results,
                      got 1, expected 5
                  contextLevel:
                    type: integer
                    description: >
                      Level indicating the position of a suggestion in a
                      hierarchy of records.


                      For example, a `contextLevel` of 1 indicates that this
                      suggestion belongs to a previous suggestion with
                      `contextLevel` 0.
                    example: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /setClientApiKey:
    get:
      x-helper: true
      x-asynchronous-helper: false
      tags:
        - Query-Suggestions
      operationId: setClientApiKey
      summary: Algolia Switch the API key used to authenticate requests
      description: |
        Switch the API key used to authenticate requests.
      parameters:
        - in: query
          name: apiKey
          description: API key to be used from now on.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No content.
components:
  securitySchemes:
    appId:
      type: apiKey
      in: header
      name: x-algolia-application-id
      description: Your Algolia application ID.
    apiKey:
      type: apiKey
      in: header
      name: x-algolia-api-key
      description: >
        Your Algolia API key with the necessary permissions to make the request.

        Permissions are controlled through access control lists (ACL) and access
        restrictions.

        The required ACL to make a request is listed in each endpoint's
        reference.
  parameters:
    PathInPath:
      name: path
      in: path
      description: Path of the endpoint, anything after "/1" must be specified.
      required: true
      schema:
        type: string
        example: /keys
    Parameters:
      name: parameters
      in: query
      description: Query parameters to apply to the current query.
      schema:
        type: object
        additionalProperties: true
    IndexName:
      name: indexName
      in: path
      required: true
      description: Query Suggestions index name.
      schema:
        $ref: '#/components/schemas/IndexName'
  schemas:
    ErrorBase:
      description: Error.
      type: object
      x-keep-model: true
      additionalProperties: true
      properties:
        message:
          type: string
          example: Invalid Application-Id or API-Key
    AppID:
      type: object
      properties:
        appID:
          type: string
          description: >-
            Algolia application ID to which this Query Suggestions configuration
            belongs.
    IndexName:
      title: indexName
      type: string
      description: Name of the Query Suggestions index (case-sensitive).
      example: products_query_suggestions
    AnalyticsTags:
      title: analyticsTags
      description: >
        Analytics tags for filtering the popular searches.

        For more information, see [Segment your analytics
        data](https://www.algolia.com/doc/guides/search-analytics/guides/segments/).
      default:
      oneOf:
        - type: array
          items:
            type: string
        - type: 'null'
    Facet:
      type: object
      description: Facet to use as category.
      properties:
        attribute:
          type: string
          description: Facet name.
        amount:
          type: integer
          description: Number of suggestions.
    Facets:
      title: facets
      description: >
        Facets to use as top categories with your suggestions.


        If provided, Query Suggestions adds the top facet values to each
        suggestion.
      default:
      oneOf:
        - type: array
          items:
            $ref: '#/components/schemas/Facet'
        - type: 'null'
      example:
        - attribute: category
          amount: 3
        - attribute: brand
          amount: 2
    Generate:
      title: generate
      description: >
        Facets used for generating query suggestions from facet values.


        For example, if you set `generate: ["color", "brand"]`, combinations
        from the facet values are added as query suggestions,

        such as "blue adidas", "red adidas", "blue nike", "red nike", etc.


        You can include nested lists.
      default:
      oneOf:
        - type: array
          items:
            type: array
            items:
              type: string
        - type: 'null'
      example:
        -   - color
            - brand
    External:
      description: >
        Algolia indices with popular searches to use as query suggestions.


        Records of these indices must have these attributes:


        - `query`: search query which will be added as a suggestion

        - `count`: measure of popularity of that search query


        For example, you can export popular searches from an external analytics
        provider, such as Google Analytics or Adobe Analytics,

        and feed this data into an Algolia index.

        You can use this index to generate query suggestions until your Algolia
        Analytics has collected enough data.
      default:
      oneOf:
        - type: array
          items:
            type: string
        - type: 'null'
    SourceIndex:
      type: object
      description: Configuration of an Algolia index for Query Suggestions.
      required:
        - indexName
      properties:
        indexName:
          type: string
          description: >-
            Name of the Algolia index (case-sensitive) to use as source for
            query suggestions.
          example: products
        replicas:
          type: boolean
          default: false
          description: >
            If true, Query Suggestions uses all replica indices to find popular
            searches.

            If false, only the primary index is used.
          example: false
        analyticsTags:
          $ref: '#/components/schemas/AnalyticsTags'
        facets:
          $ref: '#/components/schemas/Facets'
        minHits:
          type: integer
          minimum: 0
          default: 5
          description: >
            Minimum number of hits required to be included as a suggestion.


            A search query must at least generate `minHits` search results to be
            included in the Query Suggestions index.
        minLetters:
          type: integer
          minimum: 0
          default: 4
          description: >
            Minimum letters required to be included as a suggestion.


            A search query must be at least `minLetters` long to be included in
            the Query Suggestions index.
        generate:
          $ref: '#/components/schemas/Generate'
        external:
          $ref: '#/components/schemas/External'
    Languages:
      title: languages
      description: |
        Languages for deduplicating singular and plural suggestions.
        If specified, only the more popular form is included.
      default: false
      oneOf:
        - type: array
          description: Languages for which to deduplicate singular and plural forms.
          items:
            type: string
            description: Two-letter country code.
        - type: boolean
          description: If true, deduplication is enabled for all languages.
    Exclude:
      title: exclude
      description: Words or regular expressions to exclude from the suggestions.
      default:
      oneOf:
        - type: array
          items:
            type: string
        - type: 'null'
    Configuration:
      type: object
      description: Query Suggestions configuration.
      required:
        - sourceIndices
      properties:
        sourceIndices:
          type: array
          description: >-
            Algolia indices from which to get the popular searches for query
            suggestions.
          minItems: 1
          items:
            $ref: '#/components/schemas/SourceIndex'
        languages:
          $ref: '#/components/schemas/Languages'
        exclude:
          $ref: '#/components/schemas/Exclude'
        enablePersonalization:
          type: boolean
          default: false
          description: Whether to turn on personalized query suggestions.
        allowSpecialCharacters:
          type: boolean
          default: false
          description: Whether to include suggestions with special characters.
    ConfigurationWithIndex:
      type: object
      description: Query Suggestions configuration.
      required:
        - indexName
        - sourceIndices
      allOf:
        - type: object
          additionalProperties: false
          properties:
            indexName:
              $ref: '#/components/schemas/IndexName'
        - $ref: '#/components/schemas/Configuration'
    ConfigurationResponse:
      type: object
      description: API response for retrieving Query Suggestions configurations.
      allOf:
        - $ref: '#/components/schemas/AppID'
        - $ref: '#/components/schemas/ConfigurationWithIndex'
      required:
        - appID
        - allowSpecialCharacters
        - enablePersonalization
        - exclude
        - languages
        - sourceIndices
    BaseResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code.
        message:
          type: string
          description: Details about the response, such as error messages.
    LogLevel:
      title: level
      type: string
      description: >
        Type of log entry.


        - `SKIP`. A query is skipped because it doesn't match the conditions for
        successful inclusion. For example, when a query doesn't generate enough
        search results.

        - `INFO`. An informative log entry.

        - `ERROR`. The Query Suggestions process encountered an error.
      enum:
        - SKIP
        - INFO
        - ERROR
  responses:
    BadRequest:
      description: Bad request or request arguments.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    FeatureNotEnabled:
      description: This feature is not enabled on your Algolia account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    MethodNotAllowed:
      description: Method not allowed with this API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    IndexNotFound:
      description: Index not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BaseResponse'
          examples:
            Unauthorized:
              summary: Wrong region
              description: >
                Make sure to make your request to the server corresponding to
                your region.


                You can check the region for your application in the [Algolia
                dashboard](https://dashboard.algolia.com/account/infrastructure/analytics).
              value:
                status: 401
                message: The log processing region does not match.
            InvalidCredentials:
              summary: Invalid credentials
              description: Your application ID or API key is wrong.
              value:
                status: 401
                message: Invalid credentials
            MissingACL:
              summary: Key is missing ACL
              description: Your API key is missing the required ACL for this operation.
              value:
                status: 401
                message: The provided API key is missing the \"editSettings\" ACL.
    BadRequest-2:
      description: Bad Request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BaseResponse'
          examples:
            IndexNameRequired:
              summary: Index name required
              value:
                status: 400
                message: IndexName cannot be empty.
            SourceIndicesRequired:
              summary: Source indices required
              value:
                status: 400
                message: >-
                  Invalid body "sourceIndices needs to contain at least one
                  index".
            SourceIndexNameRequired:
              summary: Source index name required
              value:
                status: 400
                message: Invalid body "every source index must have an `indexName`".
            MinHitsPositive:
              summary: MinHits must be positive
              value:
                status: 400
                message: Invalid body "every source index `minHits` must be positive".
            MinLettersPositive:
              summary: MinLetters must be positive
              value:
                status: 400
                message: >-
                  Invalid body "every source index `minLetters` must be
                  positive".
    UnprocessableEntity:
      description: Unprocessable Entity.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BaseResponse'
          examples:
            UnprocessableEntity:
              summary: Configuration already exists
              value:
                status: 422
                message: 'Configuration already exists for index: test-qs'
    InternalError:
      description: Internal error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    NotFound:
      description: Not Found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BaseResponse'
          examples:
            NotFound:
              summary: Index not found
              value:
                status: 404
                message: Not Found
    InternalError-2:
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BaseResponse'
          examples:
            Error:
              description: >-
                This error can happen if you use a non-existing `indexName` as a
                path parameter when trying to update or delete a Query
                Suggestions configuration.
              value:
                status: 500
                message: Internal Server Error
x-tagGroups:
  - name: Configurations
    tags:
      - configurations
  - name: Logs
    tags:
      - logs