Algolia Query Suggestions API

openapi: 3.2.0
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.\nIn 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.\n\n## Base URLs\n\nBase URLs for the Query Suggestions API:\n\n- `https://query-suggestions.us.algolia.com`\n- `https://query-suggestions.eu.algolia.com`\n\nUse the URL that matches your [analytics region](https://dashboard.algolia.com/account/infrastructure/analytics).\n\n**All requests must use HTTPS.**\n\n## Authentication\n\nAdd these headers to authenticate requests:\n\n- `x-algolia-application-id`. Your Algolia application ID.\n- `x-algolia-api-key`. An API key with the necessary permissions to make the request.\n  The required access control list (ACL) to make a request is listed in each endpoint's reference.\n\nYou can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys).\n\n## Request format\n\nRequest bodies must be JSON objects.\n\n## Response status and errors\n\nResponse bodies are JSON objects.\nDeleting a user token returns an empty response body with rate-limiting information as headers.\n\nSuccessful responses return `2xx` statuses. Client errors return `4xx` statuses. Server errors return `5xx` statuses.\nError responses have a `message` property with more information.\n\n## Version\n\nThe current version of the Query Suggestions API is version 1, indicated by the `/1/` in each endpoint's URL.\n"
  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:
      description: The region where your Algolia application is hosted.
      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 lets you 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 lets you 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 lets you 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 lets you 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-mcp-tool: true
      x-acl:
      - settings
      summary: 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-mcp-tool: true
      x-acl:
      - editSettings
      summary: 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-mcp-tool: true
      x-acl:
      - settings
      summary: 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-mcp-tool: true
      x-acl:
      - editSettings
      summary: 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: 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-mcp-tool: true
      x-acl:
      - settings
      summary: 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-mcp-tool: true
      x-acl:
      - settings
      summary: 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
      x-acl: []
      tags:
      - query-suggestions
      operationId: setClientApiKey
      summary: 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 use for subsequent requests.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No content.
components:
  schemas:
    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: ALGOLIA_INDEX_NAME
    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.
    BaseResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code.
        message:
          type: string
          description: Details about the response, such as error messages.
    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
    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.
    Exclude:
      title: exclude
      description: Words or regular expressions to exclude from the suggestions.
      default: null
      oneOf:
      - type: array
        items:
          type: string
      - type: 'null'
    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: null
      oneOf:
      - type: array
        items:
          $ref: '#/components/schemas/Facet'
      - type: 'null'
      example:
      - attribute: category
        amount: 3
      - attribute: brand
        amount: 2
    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'
    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
    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: null
      oneOf:
      - type: array
        items:
          type: array
          items:
            type: string
      - type: 'null'
      example:
      - - color
        - brand
    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'
    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: null
      oneOf:
      - type: array
        items:
          type: string
      - type: 'null'
    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: null
      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.
    ErrorBase:
      description: Error.
      type: object
      x-keep-model: true
      additionalProperties: true
      properties:
        message:
          type: string
          example: Invalid Application-Id or API-Key
  parameters:
    PathInPath:
      name: path
      in: path
      description: Path of the endpoint, for example `1/newFeature`.
      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'
  responses:
    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'
    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.
    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
    MethodNotAllowed:
      description: Method not allowed with this API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    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
    IndexNotFound:
      description: Index not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    BadRequest:
      description: Bad request or request arguments.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    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".
    FeatureNotEnabled:
      description: This feature is not enabled on your Algolia account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
  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.

        '
x-tagGroups:
- name: Configurations
  tags:
  - configurations
- name: Logs
  tags:
  - logs