openapi: 3.0.2
info:
  title: Query Suggestions API
  description: API powering the Query Suggestions feature of Algolia.
  version: 0.0.1
components:
  securitySchemes:
    appId:
      type: apiKey
      in: header
      name: X-Algolia-Application-Id
    apiKey:
      type: apiKey
      in: header
      name: X-Algolia-API-Key
  parameters:
    PathInPath:
      name: path
      in: path
      description: >-
        The path of the API endpoint to target, anything after the /1 needs to
        be specified.
      required: true
      schema:
        type: string
        example: /keys
    Parameters:
      name: parameters
      in: query
      description: Query parameters to be applied to the current query.
      schema:
        type: object
        additionalProperties: true
    IndexName:
      name: indexName
      in: path
      description: The index in which to perform the request.
      required: true
      schema:
        type: string
        example: myIndexName
  schemas:
    ErrorBase:
      description: Error.
      type: object
      additionalProperties: true
      properties:
        message:
          type: string
          example: Invalid Application-Id or API-Key
    indexName:
      type: string
      description: Source index name.
    analyticsTags:
      type: array
      items:
        type: string
      default: []
      description: List of analytics tags to filter the popular searches per tag.
    facets:
      type: array
      items:
        type: object
      default: []
      description: List of facets to define as categories for the query suggestions.
    minHits:
      type: integer
      description: >-
        Minimum number of hits (e.g., matching records in the source index) to
        generate a suggestions.
    minLetters:
      type: integer
      description: Minimum number of required letters for a suggestion to remain.
    generate:
      type: array
      items:
        type: array
        items:
          type: string
      default: []
      description: >-
        List of facet attributes used to generate Query Suggestions. The
        resulting suggestions are every combination of the facets in the nested
        list (e.g., (facetA and facetB) and facetC).
      example: '[[facetA, facetB], [facetC]]'
    SourceIndexExternal:
      type: object
      additionalProperties: false
      required:
        - query
        - count
      properties:
        query:
          type: string
          description: The suggestion you would like to add.
        count:
          type: integer
          description: The measure of the suggestion relative popularity.
    external:
      type: array
      items:
        $ref: '#/components/schemas/SourceIndexExternal'
      description: List of external indices to use to generate custom Query Suggestions.
    SourceIndiceWithReplicas:
      type: object
      additionalProperties: false
      description: Source indice with replicas used to generate a Query Suggestions index.
      required:
        - replicas
        - indexName
        - analyticsTags
        - facets
        - minHits
        - minLetters
        - generate
        - external
      properties:
        replicas:
          type: boolean
          description: true if the Query Suggestions index is a replicas.
        indexName:
          $ref: '#/components/schemas/indexName'
        analyticsTags:
          $ref: '#/components/schemas/analyticsTags'
        facets:
          $ref: '#/components/schemas/facets'
        minHits:
          $ref: '#/components/schemas/minHits'
        minLetters:
          $ref: '#/components/schemas/minLetters'
        generate:
          $ref: '#/components/schemas/generate'
        external:
          $ref: '#/components/schemas/external'
    SourceIndicesWithReplicas:
      type: array
      description: List of source indices used to generate a Query Suggestions index.
      items:
        $ref: '#/components/schemas/SourceIndiceWithReplicas'
    QuerySuggestionsIndex:
      type: object
      additionalProperties: false
      required:
        - indexName
        - sourceIndices
        - languages
        - exclude
      properties:
        indexName:
          type: string
          description: Index name to target.
        sourceIndices:
          $ref: '#/components/schemas/SourceIndicesWithReplicas'
        languages:
          type: array
          items:
            type: string
          description: >-
            De-duplicate singular and plural suggestions. For example, let's say
            your index contains English content, and that two suggestions “shoe”
            and “shoes” end up in your Query Suggestions index. If the English
            language is configured, only the most popular of those two
            suggestions would remain.
        exclude:
          type: array
          items:
            type: string
          description: >-
            List of words and patterns to exclude from the Query Suggestions
            index.
    SourceIndex:
      type: object
      additionalProperties: false
      required:
        - indexName
      properties:
        indexName:
          $ref: '#/components/schemas/indexName'
        analyticsTags:
          $ref: '#/components/schemas/analyticsTags'
        facets:
          $ref: '#/components/schemas/facets'
        minHits:
          $ref: '#/components/schemas/minHits'
        minLetters:
          $ref: '#/components/schemas/minLetters'
        generate:
          $ref: '#/components/schemas/generate'
        external:
          $ref: '#/components/schemas/external'
    SourceIndices:
      type: array
      items:
        $ref: '#/components/schemas/SourceIndex'
      description: List of source indices used to generate a Query Suggestions index.
    QuerySuggestionsIndexParam:
      type: object
      additionalProperties: false
      required:
        - sourceIndices
      properties:
        sourceIndices:
          $ref: '#/components/schemas/SourceIndices'
        languages:
          type: array
          items:
            type: string
          description: >-
            De-duplicate singular and plural suggestions. For example, let's say
            your index contains English content, and that two suggestions “shoe”
            and “shoes” end up in your Query Suggestions index. If the English
            language is configured, only the most popular of those two
            suggestions would remain.
        exclude:
          type: array
          items:
            type: string
          description: >-
            List of words and patterns to exclude from the Query Suggestions
            index.
    QuerySuggestionsIndexWithIndexParam:
      allOf:
        - $ref: '#/components/schemas/QuerySuggestionsIndexParam'
        - type: object
          title: IndexName
          additionalProperties: false
          required:
            - indexName
          properties:
            indexName:
              type: string
              description: Index name to target.
    logLevel:
      type: string
      enum:
        - INFO
        - SKIP
        - ERROR
      description: type of the record, can be one of three values (INFO, SKIP or 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/ErrorBase'
    StatusUnprocessableEntity:
      description: Status unprocessable entity.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    InternalError:
      description: Internal error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    Success:
      description: Success
      content:
        application/json:
          schema:
            type: object
            title: SucessResponse
            additionalProperties: false
            required:
              - status
              - message
            properties:
              status:
                type: integer
                example: 200
                description: The status code.
              message:
                type: string
                example: Success
                description: Message of the response.
servers:
  - url: https://query-suggestions.{region}.algolia.com
    variables:
      region:
        enum:
          - us
          - eu
        default: us
security:
  - appId: []
    apiKey: []
tags:
  - name: advanced
    x-displayName: Advanced
    description: Advanced operations.
  - name: configurations
    x-displayName: Configurations
    description: Manage Query Suggestions configurations.
x-tagGroups:
  - name: General
    tags:
      - configurations
  - name: Others
    tags:
      - advanced
paths:
  /1{path}:
    get:
      operationId: get
      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'
    post:
      operationId: post
      requestBody:
        description: The 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'
    put:
      operationId: put
      requestBody:
        description: The 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'
    delete:
      operationId: del
      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'
  /1/configs:
    get:
      tags:
        - configurations
      operationId: getAllConfigs
      summary: List configurations
      description: >
        Get all the configurations of Query Suggestions.

        For each index, you get a block of JSON with a list of its configuration
        settings.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/QuerySuggestionsIndex'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '422':
          $ref: '#/components/responses/StatusUnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags:
        - configurations
      operationId: createConfig
      summary: Create a configuration
      description: >-
        Create a configuration of a Query Suggestions index. There's a limit of
        100 configurations per application.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuerySuggestionsIndexWithIndexParam'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '422':
          $ref: '#/components/responses/StatusUnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /1/configs/{indexName}:
    get:
      tags:
        - configurations
      operationId: getConfig
      summary: Get a single configuration
      description: Get the configuration of a single Query Suggestions index.
      parameters:
        - $ref: '#/components/parameters/IndexName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuerySuggestionsIndex'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      tags:
        - configurations
      operationId: updateConfig
      summary: Update a configuration
      description: Update the configuration of a Query Suggestions index.
      parameters:
        - $ref: '#/components/parameters/IndexName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuerySuggestionsIndexParam'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags:
        - configurations
      operationId: deleteConfig
      summary: Delete a configuration
      description: >
        Delete a configuration of a Query Suggestion's index.

        By deleting a configuraton, you stop all updates to the underlying query
        suggestion index.

        Note that when doing this, the underlying index does not change -
        existing suggestions remain untouched.
      parameters:
        - $ref: '#/components/parameters/IndexName'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/InternalError'
  /1/configs/{indexName}/status:
    get:
      tags:
        - configurations
      operationId: getConfigStatus
      summary: Get configuration status
      description: >
        Get the status of a Query Suggestion's index.

        The status includes whether the Query Suggestions index is currently in
        the process of being built, and the last build time.
      parameters:
        - $ref: '#/components/parameters/IndexName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                title: Status
                additionalProperties: false
                required:
                  - indexName
                  - isRunning
                  - lastBuiltAt
                properties:
                  indexName:
                    type: string
                    description: The targeted index name.
                  isRunning:
                    type: boolean
                    description: true if the Query Suggestions index is running.
                  lastBuiltAt:
                    type: string
                    format: data-time
                    description: Date and time of the last build.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/InternalError'
  /1/logs/{indexName}:
    get:
      tags:
        - advanced
      operationId: getLogFile
      summary: Get a log file
      description: Get the log file of the last build of a single Query Suggestion index.
      parameters:
        - $ref: '#/components/parameters/IndexName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  title: LogFile
                  additionalProperties: false
                  required:
                    - timestamp
                    - level
                    - message
                    - contextLevel
                  properties:
                    timestamp:
                      type: string
                      description: date and time of creation of the record.
                    level:
                      $ref: '#/components/schemas/logLevel'
                    message:
                      type: string
                      description: detailed description of what happened.
                    contextLevel:
                      type: integer
                      description: >-
                        indicates the hierarchy of the records. For example, a
                        record with contextLevel=1 belongs to a preceding record
                        with contextLevel=0.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
