openapi: 3.0.2
info:
  title: Search API
  summary: The Algolia Search API lets you search, configure, and manage your indices and records
  description: |
    ## Client libraries

    Use Algolia's API clients and libraries to reliably integrate Algolia's APIs with your apps.
    The official API clients are covered by Algolia's [Service Level Agreement](https://www.algolia.com/policies/sla).

    For more information, see [Algolia's ecosystem](https://www.algolia.com/doc/libraries).

    ## Base URLs

    Base URLs for the Search API:

    - `https://{APPLICATION_ID}.algolia.net`
    - `https://{APPLICATION_ID}-dsn.algolia.net`.
      If your subscription includes a [Distributed Search Network](https://dashboard.algolia.com/infra),
      this ensures that requests are sent to servers closest to users.

    Both URLs provide high availability by distributing requests with load balancing.

    **All requests must use HTTPS.**

    ## Retry strategy

    To guarantee high availability, implement a retry strategy for all API requests using the URLs of your servers as fallbacks:

    - `https://{APPLICATION_ID}-1.algolianet.com`
    - `https://{APPLICATION_ID}-2.algolianet.com`
    - `https://{APPLICATION_ID}-3.algolianet.com`

    These URLs use a different DNS provider than the primary URLs.
    Randomize this list to ensure an even load across the three servers.

    All Algolia API clients implement this retry strategy.

    ## 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

    Depending on the endpoint, request bodies are either JSON objects or arrays of JSON objects.

    ## Parameters

    Parameters are passed as query parameters for GET and DELETE requests,
    and in the request body for POST and PUT requests.

    Query parameters must be [URL-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding).
    Non-ASCII characters must be UTF-8 encoded.
    Plus characters (`+`) are interpreted as spaces.
    Arrays as query parameters must be one of:

    - A comma-separated string: `attributesToRetrieve=title,description`
    - A URL-encoded JSON array: `attributesToRetrieve=%5B%22title%22,%22description%22%D`

    ## Response status and errors

    The Search API returns JSON responses.
    Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response.

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

    ## Request identifiers

    Every response includes a `Correlation-ID` header that identifies the request in Algolia's logs.
    When contacting the Algolia support team about a specific request, include this identifier in your ticket.

    To tag requests with your own identifier, send a `Request-ID` header with exactly 11 alphanumeric characters.
    Clusters that support it embed the identifier at the end of the `Correlation-ID`,
    so all attempts of a retried operation can be found by searching for those characters.
    Headers that don't match the expected format are ignored.

    Don't use the `Correlation-ID` as a unique key: retried requests may receive the same identifier.

    ## Version

    The current version of the Search 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'
  schemas:
    attributeToUpdate:
      $ref: 'paths/objects/common/schemas.yml#/attributeToUpdate'
servers:
  - url: https://{appId}.algolia.net
    variables:
      appId:
        default: ALGOLIA_APPLICATION_ID
  - url: https://{appId}-1.algolianet.com
    variables:
      appId:
        default: ALGOLIA_APPLICATION_ID
  - url: https://{appId}-2.algolianet.com
    variables:
      appId:
        default: ALGOLIA_APPLICATION_ID
  - url: https://{appId}-3.algolianet.com
    variables:
      appId:
        default: ALGOLIA_APPLICATION_ID
  - url: https://{appId}-dsn.algolia.net
    variables:
      appId:
        default: ALGOLIA_APPLICATION_ID
security:
  - appId: []
    apiKey: []
tags:
  - name: Advanced
    description: Query your logs.
  - name: Api Keys
    x-displayName: API keys
    description: |
      Manage your API keys.

      API requests must be authenticated with an API key.
      API keys can have permissions (access control lists, ACL) and restrictions.
    externalDocs:
      url: https://www.algolia.com/doc/guides/security/api-keys
      description: API keys.

  - name: Clusters
    description: |
      Multi-cluster operations.

      Multi-cluster operations are **deprecated**.
      If you have issues with your Algolia infrastructure
      due to large volumes of data, contact the Algolia support team.
  - name: Dictionaries
    description: |
      Manage your dictionaries.

      Customize language-specific settings, such as stop words, plurals, or word segmentation.

      Dictionaries are application-wide.
    externalDocs:
      url: https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp
      description: Natural languages.
  - name: Indices
    description: |
      Manage your indices and index settings.

      Indices are copies of your data that are stored on Algolia's servers.
      They're optimal data structures for fast search and are made up of records and settings.
    externalDocs:
      url: https://www.algolia.com/doc/guides/sending-and-managing-data/manage-indices-and-apps/manage-indices
      description: Manage your indices.
  - name: Records
    description: |
      Add, update, and delete records from your indices.

      Records are individual items in your index.
      When they match a search query, they're returned as search results, in the order determined by your ranking.
      Records are schemaless JSON objects.
      When adding or updating many records, check the [indexing rate limits](https://support.algolia.com/hc/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
    externalDocs:
      url: https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data
      description: Prepare your records.
  - name: Rules
    description: |
      Create, update, delete, and search for rules.

      Rules are _if-then_ statements that you can use to curate search results.
      Rules have _conditions_ that can trigger _consequences_.
      Consequences are changes to the search results, such as changing the order of search results or boosting a facet.
      This can be useful for tuning specific queries or for merchandising.
    externalDocs:
      url: https://www.algolia.com/doc/guides/managing-results/rules/rules-overview
      description: Index Rules.
  - name: Search
    description: Search one or more indices for matching records or facet values.
  - name: Synonyms
    description: |
      Create, update, delete, and search for synonyms.

      Synonyms are terms that the search engine should consider equal.
    externalDocs:
      url: https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms
      description: Synonyms.
  - name: Vaults
    description: Algolia Vault lets you restrict access to your clusters to specific IP addresses and provides disk-level encryption at rest.
    externalDocs:
      url: https://www.algolia.com/doc/guides/security/algolia-vault
      description: Algolia Vault.
  - name: _model_index_settings
    x-displayName: Index settings
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/indexSettings" />.
x-tagGroups:
  - name: Search and indexing
    tags:
      - Indices
      - Records
      - Search
  - name: Relevance
    tags:
      - Rules
      - Synonyms
      - Dictionaries
  - name: Others
    tags:
      - Api Keys
      - Clusters
      - Vaults
      - Advanced
  - name: Models
    tags:
      - _model_index_settings
paths:
  # ######################
  # ### Custom request ###
  # ######################
  /{path}:
    $ref: '../common/paths/customRequest.yml'

  # ########################
  # ### Search Endpoints ###
  # ########################
  /1/indexes/{indexName}/query:
    $ref: 'paths/search/searchSingleIndex.yml'
  /1/indexes/*/queries:
    $ref: 'paths/search/search.yml'
  /1/indexes/{indexName}/facets/{facetName}/query:
    $ref: 'paths/search/searchForFacetValues.yml'
  /1/indexes/{indexName}/browse:
    $ref: 'paths/search/browse.yml'

  # #########################
  # ### Objects Endpoints ###
  # #########################
  /1/indexes/{indexName}:
    $ref: 'paths/objects/objects.yml'
  /1/indexes/{indexName}/{objectID}:
    $ref: 'paths/objects/object.yml'
  /1/indexes/{indexName}/deleteByQuery:
    $ref: 'paths/objects/deleteBy.yml'
  /1/indexes/{indexName}/clear:
    $ref: 'paths/objects/clearObjects.yml'
  /1/indexes/{indexName}/{objectID}/partial:
    $ref: 'paths/objects/partialUpdate.yml'
  /1/indexes/{indexName}/batch:
    $ref: 'paths/objects/batch.yml'
  /1/indexes/*/batch:
    $ref: 'paths/objects/multipleBatch.yml'
  /1/indexes/*/objects:
    $ref: 'paths/objects/getObjects.yml'

  # ##########################
  # ### Settings Endpoints ###
  # ##########################
  /1/indexes/{indexName}/settings:
    $ref: 'paths/settings/settings.yml'

  # ##########################
  # ### Synonyms Endpoints ###
  # ##########################
  /1/indexes/{indexName}/synonyms/{objectID}:
    $ref: 'paths/synonyms/synonym.yml'
  /1/indexes/{indexName}/synonyms/batch:
    $ref: 'paths/synonyms/saveSynonyms.yml'
  /1/indexes/{indexName}/synonyms/clear:
    $ref: 'paths/synonyms/clearSynonyms.yml'
  /1/indexes/{indexName}/synonyms/search:
    $ref: 'paths/synonyms/searchSynonyms.yml'

  # ######################
  # ### Keys Endpoints ###
  # ######################
  /1/keys:
    $ref: 'paths/keys/keys.yml'
  /1/keys/{key}:
    $ref: 'paths/keys/key.yml'
  /1/keys/{key}/restore:
    $ref: 'paths/keys/restoreApiKey.yml'

  # #######################
  # ### Rules Endpoints ###
  # #######################
  /1/indexes/{indexName}/rules/{objectID}:
    $ref: 'paths/rules/rule.yml'
  /1/indexes/{indexName}/rules/batch:
    $ref: 'paths/rules/saveRules.yml'
  /1/indexes/{indexName}/rules/clear:
    $ref: 'paths/rules/clearRules.yml'
  /1/indexes/{indexName}/rules/search:
    $ref: 'paths/rules/searchRules.yml'

  # ##############################
  # ### Dictionaries Endpoints ###
  # ##############################
  /1/dictionaries/{dictionaryName}/batch:
    $ref: 'paths/dictionaries/batchDictionaryEntries.yml'
  /1/dictionaries/{dictionaryName}/search:
    $ref: 'paths/dictionaries/searchDictionaryEntries.yml'
  /1/dictionaries/*/settings:
    $ref: 'paths/dictionaries/dictionarySettings.yml'
  /1/dictionaries/*/languages:
    $ref: 'paths/dictionaries/getDictionaryLanguages.yml'

  # ###############################
  # ### MultiClusters Endpoints ###
  # ###############################
  /1/clusters/mapping:
    $ref: 'paths/multiclusters/userIds.yml'
  /1/clusters/mapping/batch:
    $ref: 'paths/multiclusters/batchAssignUserIds.yml'
  /1/clusters/mapping/top:
    $ref: 'paths/multiclusters/getTopUserIds.yml'
  /1/clusters/mapping/{userID}:
    $ref: 'paths/multiclusters/userId.yml'
  /1/clusters:
    $ref: 'paths/multiclusters/listClusters.yml'
  /1/clusters/mapping/search:
    $ref: 'paths/multiclusters/searchUserIds.yml'
  /1/clusters/mapping/pending:
    $ref: 'paths/multiclusters/hasPendingMappings.yml'

  # #######################
  # ### Vault Endpoints ###
  # #######################
  /1/security/sources:
    $ref: 'paths/vault/vaultSources.yml'
  /1/security/sources/append:
    $ref: 'paths/vault/appendSource.yml'
  /1/security/sources/{source}:
    $ref: 'paths/vault/deleteSource.yml'

  # ##########################
  # ### Advanced Endpoints ###
  # ##########################
  /1/logs:
    $ref: 'paths/advanced/getLogs.yml'
  /1/task/{taskID}:
    $ref: 'paths/advanced/getAppTask.yml'
  /1/indexes/{indexName}/task/{taskID}:
    $ref: 'paths/advanced/getTask.yml'

  # ################################
  # ### Manage Indices Endpoints ###
  # ################################
  /1/indexes/{indexName}/operation:
    $ref: 'paths/manage_indices/operationIndex.yml'
  /1/indexes:
    $ref: 'paths/manage_indices/listIndices.yml'

  # ###############
  # ### Helpers ###
  # ###############
  /waitForApiKey:
    $ref: 'helpers/waitForApiKey.yml#/method'

  /waitForTask:
    $ref: 'helpers/waitForTask.yml#/method'

  /waitForAppTask:
    $ref: 'helpers/waitForAppTask.yml#/method'

  /browseObjects:
    $ref: 'helpers/browseObjects.yml#/method'

  /generateSecuredApiKey:
    $ref: 'helpers/generateSecuredApiKey.yml#/method'

  /accountCopyIndex:
    $ref: 'helpers/accountCopyIndex.yml#/method'

  /replaceAllObjects:
    $ref: 'helpers/replaceAllObjects.yml#/method'

  /replaceAllObjectsWithTransformation:
    $ref: 'helpers/replaceAllObjectsWithTransformation.yml#/method'

  /chunkedBatch:
    $ref: 'helpers/chunkedBatch.yml#/method'

  /saveObjects:
    $ref: 'helpers/saveObjects.yml#/method'

  /saveObjectsWithTransformation:
    $ref: 'helpers/saveObjectsWithTransformation.yml#/method'

  /deleteObjects:
    $ref: 'helpers/deleteObjects.yml#/method'

  /partialUpdateObjects:
    $ref: 'helpers/partialUpdateObjects.yml#/method'

  /partialUpdateObjectsWithTransformation:
    $ref: 'helpers/partialUpdateObjectsWithTransformation.yml#/method'

  /indexExists:
    $ref: 'helpers/indexExists.yml#/method'

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