openapi: 3.0.2
info:
  title: Search API
  description: |
    The Algolia Search API lets you search, configure, and mange your indices and records.

    # 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/).

    See: [Algolia's ecosystem](https://www.algolia.com/doc/guides/getting-started/how-algolia-works/in-depth/ecosystem/)

    # Base URLs

    The base URLs for making requests to the Search API are:

    - `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 a 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.
    You should randomize this list to ensure an even load across the three servers.

    All Algolia API clients implement this retry strategy.

    # Authentication

    To authenticate your API requests, add these headers:

    <dl>
    <dt><code>x-algolia-application-id</code></dt>
    <dd>Your Algolia application ID.</dd>
    <dt><code>x-algolia-api-key</code></dt>
    <dd>
    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.
    </dd>
    </dl>

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

    # 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 a `2xx` status. Client errors return a `4xx` status. Server errors are indicated by a `5xx` status.
    Error responses have a `message` property with more information.

    # Version

    The current version of the Search API is version 1, as 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://{appId}.algolia.net
    variables:
      appId:
        default: myAppId
  - url: https://{appId}-1.algolianet.com
    variables:
      appId:
        default: myAppId
  - url: https://{appId}-2.algolianet.com
    variables:
      appId:
        default: myAppId
  - url: https://{appId}-3.algolianet.com
    variables:
      appId:
        default: myAppId
  - url: https://{appId}-dsn.algolia.net
    variables:
      appId:
        default: myAppId
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: |
        Related guide: API keys.

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

      Algolia no longer offers multi-cluster management.
    externalDocs:
      url: https://www.algolia.com/doc/guides/scaling/managing-multiple-clusters-mcm/
      description: |
        Related guide: Multi-cluster management.
  - 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: |
        Related guide: 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: |
        Related guide: 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.
    externalDocs:
      url: https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data/
      description: |
        Related guide: 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_ which 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: |
        Related guide: 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: |
        Related guide: 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: |
        Related guide: 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 ###
  # ######################
  /1{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/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'

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