openapi: 3.0.2
info:
  title: Algolia Crawler API
  description: >-
    Algolia Crawler API is a powerful tool that allows developers to easily
    scrape and index data from websites in order to make it searchable and
    discoverable through Algolia's search engine. The API enables users to
    specify which pages and data they want to crawl, set up custom rules for how
    the data should be processed, and monitor the crawling process in real-time.
    By providing a seamless way to collect and organize information from the
    web, Algolia Crawler API helps businesses and organizations enhance the user
    experience by delivering relevant and up-to-date search results.
  version: 1.0.0
servers:
  - url: https://crawler.algolia.com/api
    description: The URL of the Crawler API.
security:
  - BasicAuth: []
tags:
  - name: actions
    x-displayName: Actions
    description: >
      Actions change the state of crawlers, such as pausing and unpausing
      schedules or testing the crawler with specific URLs.
  - name: config
    x-displayName: Configuration
    description: >
      In the Crawler configuration, you specify which URLs to crawl, when to
      crawl, how to extract records from the crawl, and where to index the
      extracted records.


      The configuration is versioned, so you can always restore a previous
      version.


      It's easiest to make configuration changes on the [Crawler
      page](https://dashboard.algolia.com/crawler) in the Algolia dashboard.

      The editor has autocomplete and built-in validation so you can try your
      configuration changes before committing them.
  - name: crawlers
    x-displayName: Crawler
    description: |
      A crawler is an object with a name and a [configuration](#tag/config).
      Use these endpoints to create, rename, and delete crawlers.
  - name: domains
    x-displayName: Domains
    description: List registered domains.
  - name: tasks
    x-displayName: Tasks
    description: Task operations.
paths:
  /1/crawlers:
    get:
      operationId: listCrawlers
      summary: List crawlers
      description: Lists all your crawlers.
      tags:
        - crawler
      parameters:
        - $ref: '#/components/parameters/ItemsPerPage'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Name'
        - $ref: '#/components/parameters/AppID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/crawlersResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/MissingAuthorization'
        '403':
          description: Invalid credentials.
        '404':
          description: The call does not have results for this combinaison of query params.
    post:
      operationId: createCrawler
      summary: Create a crawler
      description: Creates a new crawler with the provided configuration.
      tags:
        - crawler
      requestBody:
        content:
          application/json:
            schema:
              title: crawlerCreate
              type: object
              properties:
                name:
                  $ref: '#/components/schemas/CrawlerName'
                config:
                  $ref: '#/components/schemas/Configuration'
              required:
                - name
                - config
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: crawlerCreateResponse
                type: object
                properties:
                  id:
                    $ref: '#/components/schemas/CrawlerID'
                required:
                  - id
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/MissingAuthorization'
        '403':
          description: The user doesn't have enough rights to create a Crawler.
  /1/crawlers/{id}:
    get:
      operationId: getCrawler
      summary: Retrieve crawler details
      description: >
        Retrieves details about the specified crawler, optionally with its
        configuration.
      tags:
        - crawler
      parameters:
        - $ref: '#/components/parameters/CrawlerIdParameter'
        - in: query
          name: withConfig
          schema:
            type: boolean
          description: Whether the response should include the crawler's configuration.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCrawlerResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/MissingAuthorization'
        '403':
          $ref: '#/components/responses/NoRightsOnCrawler'
    patch:
      operationId: patchCrawler
      summary: Change crawler name
      description: >
        Change the crawler's name.


        While you _could_ use this endpoint to replace the crawler
        configuration,

        you should [update it](#tag/config/operation/patchConfig) instead since
        cnfiguration changes made here aren't
        [versioned](#tag/config/operation/listConfigVersions).


        If you replace the configuration, you must provide the full
        configuration,

        including any settings you want to keep.
      tags:
        - crawler
      parameters:
        - $ref: '#/components/parameters/CrawlerIdParameter'
      requestBody:
        content:
          application/json:
            schema:
              title: patchCrawler
              type: object
              properties:
                name:
                  $ref: '#/components/schemas/CrawlerName'
                config:
                  $ref: '#/components/schemas/Configuration'
      responses:
        '200':
          $ref: '#/components/responses/ActionAcknowledged'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/MissingAuthorization'
        '403':
          $ref: '#/components/responses/NoRightsOnCrawler'
    delete:
      operationId: deleteCrawler
      summary: Delete a crawler
      description: Delete the specified crawler.
      tags:
        - crawler
      parameters:
        - $ref: '#/components/parameters/CrawlerIdParameter'
      responses:
        '200':
          $ref: '#/components/responses/ActionAcknowledged'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/MissingAuthorization'
        '403':
          $ref: '#/components/responses/NoRightsOnCrawler'
  /1/crawlers/{id}/run:
    post:
      operationId: runCrawler
      summary: Unpause a crawler
      description: |
        Unpauses the specified crawler.
        Previously ongoing crawls will be resumed.
        Otherwise, the crawler waits for its next scheduled run.
      tags:
        - crawler
      parameters:
        - $ref: '#/components/parameters/CrawlerIdParameter'
      responses:
        '200':
          $ref: '#/components/responses/ActionAcknowledged'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/MissingAuthorization'
        '403':
          $ref: '#/components/responses/NoRightsOnCrawler'
  /1/crawlers/{id}/pause:
    post:
      operationId: pauseCrawler
      summary: Pause a crawler
      description: Pauses the specified crawler.
      tags:
        - crawler
      parameters:
        - $ref: '#/components/parameters/CrawlerIdParameter'
      responses:
        '200':
          $ref: '#/components/responses/ActionAcknowledged'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/MissingAuthorization'
        '403':
          $ref: '#/components/responses/NoRightsOnCrawler'
  /1/crawlers/{id}/reindex:
    post:
      operationId: startReindex
      summary: Start a crawl
      description: Starts or resumes a crawl.
      tags:
        - crawler
      parameters:
        - $ref: '#/components/parameters/CrawlerIdParameter'
      responses:
        '200':
          $ref: '#/components/responses/ActionAcknowledged'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/MissingAuthorization'
        '403':
          $ref: '#/components/responses/NoRightsOnCrawler'
  /1/crawlers/{id}/test:
    post:
      operationId: testUrl
      summary: Test crawl a URL
      description: >
        Tests a URL with the crawler's configuration and shows the extracted
        records.


        You can test configuration changes by overriding specific parts before
        updating the full configuration.
      tags:
        - crawler
      parameters:
        - $ref: '#/components/parameters/CrawlerIdParameter'
      requestBody:
        content:
          application/json:
            schema:
              title: testUrl
              type: object
              properties:
                url:
                  type: string
                  description: URL to test.
                  example: https://www.algolia.com/blog
                config:
                  $ref: '#/components/schemas/PartialConfig'
              required:
                - url
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: urlTest
                type: object
                properties:
                  startDate:
                    type: string
                    description: >-
                      Date and time when the test crawl started, in RFC 3339
                      format.
                    example: '2024-04-02T15:34:29Z'
                  endDate:
                    type: string
                    description: >-
                      Date and time when the test crawl finished, in RFC 3339
                      format.
                    example: '2024-04-02T15:34:29Z'
                  logs:
                    type: array
                    description: Logs from the record extraction.
                    items:
                      type: array
                      description: Parameters associated with each log.
                      items:
                        type: string
                        example: Processing url 'https://www.algolia.com/blog'
                  records:
                    type: array
                    description: Extracted records from the URL.
                    items:
                      title: extractedRecords
                      type: object
                      properties:
                        indexName:
                          type: string
                          description: Name of the index where this record will be stored.
                          example: testIndex
                        records:
                          type: array
                          description: Extracted records.
                          items:
                            type: object
                            description: Algolia record.
                            example:
                              objectID: https://www.algolia.com/blog
                              numberOfLinks: 2
                        recordsPerExtractor:
                          type: array
                          description: Partial records generated by each record extractor.
                          items:
                            title: recordPerExtractor
                            type: object
                            properties:
                              index:
                                type: number
                                description: Index of the extractor.
                                minimum: 0
                              type:
                                type: string
                                description: Extractor type.
                              records:
                                type: array
                                description: Extracted records.
                                items:
                                  type: object
                          example:
                            - index: 0
                              type: custom
                              records:
                                - objectID: https://www.algolia.com/blog
                  links:
                    type: array
                    description: >
                      Links found on the page, which match the configuration and
                      would be processed.
                    items:
                      type: string
                    example:
                      - >-
                        https://blog.algolia.com/challenging-migration-heroku-google-kubernetes-engine/
                      - https://blog.algolia.com/tale-two-engines-algolia-unity/
                  externalData:
                    type: object
                    description: >
                      External data associated with the tested URL.


                      External data is refreshed automatically at the beginning
                      of the crawl.
                    example:
                      externalData1:
                        data1: val1
                        data2: val2
                      externalData2:
                        data1: val1
                        data2: val2
                  error:
                    title: urlTestError
                    type: object
                    description: An error.
                    properties:
                      code:
                        type: string
                        example: http_internal_server_error
                      message:
                        type: string
                        example: HTTP Internal Server Error (500)
                    example: {}
                required:
                  - startDate
                  - endDate
                  - logs
                  - records
                  - links
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/MissingAuthorization'
        '403':
          $ref: '#/components/responses/NoRightsOnCrawler'
  /1/crawlers/{id}/urls/crawl:
    post:
      operationId: crawlUrls
      summary: Crawl URLs
      description: >
        Crawls the specified URLs, extracts records from them, and adds them to
        the index.

        If a crawl is currently running (the crawler's `reindexing` property is
        `true`),

        the records are added to a temporary index.
      tags:
        - crawler
      parameters:
        - $ref: '#/components/parameters/CrawlerIdParameter'
      requestBody:
        content:
          application/json:
            schema:
              title: crawlUrls
              type: object
              properties:
                urls:
                  type: array
                  description: URLs to crawl.
                  items:
                    type: string
                  example:
                    - https://www.algolia.com/products/crawler/
                save:
                  type: boolean
                  description: >
                    Whether the specified URLs should be added to the
                    `extraURLs` property of the crawler configuration.

                    If unspecified, the URLs are added to the `extraUrls` field
                    only if they haven't been indexed during the last reindex.
              required:
                - urls
      responses:
        '200':
          $ref: '#/components/responses/ActionAcknowledged'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/MissingAuthorization'
        '403':
          $ref: '#/components/responses/NoRightsOnCrawler'
  /1/crawlers/{id}/stats/urls:
    get:
      operationId: getStats
      summary: Retrieve crawler stats
      description: >-
        Retrieves information about the number of crawled, skipped, and failed
        URLs.
      tags:
        - crawler
      parameters:
        - $ref: '#/components/parameters/CrawlerIdParameter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: crawlerStats
                type: object
                properties:
                  count:
                    type: integer
                    minimum: 0
                    description: Total number of crawled URLs.
                  data:
                    type: array
                    default: []
                    items:
                      $ref: '#/components/schemas/UrlsCrawledGroup'
                required:
                  - count
                  - data
        '401':
          $ref: '#/components/responses/MissingAuthorization'
        '403':
          $ref: '#/components/responses/NoRightsOnCrawler'
  /1/crawlers/{id}/config:
    patch:
      operationId: patchConfig
      summary: Update crawler configuration
      description: |
        Updates the configuration of the specified crawler.
        Every time you update the configuration, a new version is created.
      tags:
        - crawler
      parameters:
        - $ref: '#/components/parameters/CrawlerIdParameter'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartialConfig'
      responses:
        '200':
          $ref: '#/components/responses/ActionAcknowledged'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/MissingAuthorization'
        '403':
          $ref: '#/components/responses/NoRightsOnCrawler'
  /1/crawlers/{id}/config/versions:
    get:
      operationId: listConfigVersions
      summary: List configuration versions
      description: >
        Lists previous versions of the specified crawler's configuration,
        including who authored the change.

        Every time you update a crawler's
        [configuration](#tag/config/operation/patchConfig),

        a new version is added.
      tags:
        - crawler
      parameters:
        - $ref: '#/components/parameters/CrawlerIdParameter'
        - $ref: '#/components/parameters/ItemsPerPage'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/crawlerConfigVersionsResponse'
        '404':
          description: Not found.
  /1/crawlers/{id}/config/versions/{version}:
    get:
      operationId: getConfigVersion
      summary: Retrieve a configuration version
      description: |
        Retrieves the specified version of the crawler configuration.

        You can use this to restore a previous version of the configuration.
      tags:
        - crawler
      parameters:
        - $ref: '#/components/parameters/CrawlerIdParameter'
        - $ref: '#/components/parameters/CrawlerVersionParameter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: configVersion
                type: object
                properties:
                  version:
                    $ref: '#/components/schemas/version'
                  config:
                    $ref: '#/components/schemas/Configuration'
                  createdAt:
                    $ref: '#/components/schemas/createdAt'
                  authorId:
                    $ref: '#/components/schemas/authorId'
                required:
                  - version
                  - config
                  - createdAt
                  - authorId
        '404':
          description: Not found.
  /1/crawlers/{id}/tasks/{taskID}:
    get:
      operationId: getTaskStatus
      summary: Retrieve task status
      description: >-
        Retrieves the status of the specified tasks, whether they're pending or
        completed.
      tags:
        - crawler
      parameters:
        - $ref: '#/components/parameters/CrawlerIdParameter'
        - $ref: '#/components/parameters/TaskIdParameter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: taskStatus
                type: object
                properties:
                  pending:
                    type: boolean
                    description: Whether the task is pending.
                required:
                  - pending
        '401':
          $ref: '#/components/responses/MissingAuthorization'
        '403':
          $ref: '#/components/responses/NoRightsOnCrawler'
  /1/crawlers/{id}/tasks/{taskID}/cancel:
    post:
      operationId: cancelBlockingAction
      summary: Cancel a blocking task
      description: |
        Cancels a blocking task.

        Tasks that ran into an error will block your crawler's schedule.
        To unblock the crawler, cancel the blocking task.
      tags:
        - crawler
      parameters:
        - $ref: '#/components/parameters/CrawlerIdParameter'
        - $ref: '#/components/parameters/TaskIdParameter'
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/MissingAuthorization'
        '403':
          $ref: '#/components/responses/NoRightsOnCrawler'
  /1/domains:
    get:
      operationId: listDomains
      summary: List registered domains
      description: |
        Lists registered domains.

        Crawlers will only run if the URLs match any of the registered domains.
      tags:
        - crawler
      parameters:
        - $ref: '#/components/parameters/ItemsPerPage'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/AppID'
      responses:
        '200':
          description: Domains
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domainsResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/MissingAuthorization'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
  schemas:
    itemsPerPage:
      type: integer
      description: Number of items per page of the paginated API response.
      minimum: 1
      maximum: 100
      default: 20
    page:
      type: integer
      description: Current page of the paginated API response.
      minimum: 1
      maximum: 100
      default: 1
    CrawlerName:
      type: string
      maxLength: 64
      description: Name of the crawler.
      example: test-crawler
    applicationID:
      type: string
      description: |
        Algolia application ID where the crawler creates and updates indices.
        The Crawler add-on must be enabled for this application.
    total:
      type: integer
      description: Total number of retrievable items.
      example: 100
    Pagination:
      type: object
      description: Pagination information.
      properties:
        itemsPerPage:
          $ref: '#/components/schemas/itemsPerPage'
        page:
          $ref: '#/components/schemas/page'
        total:
          $ref: '#/components/schemas/total'
    CrawlerID:
      type: string
      description: Universally unique identifier (UUID) of the crawler.
      example: e0f6db8a-24f5-4092-83a4-1b2c6cb6d809
    crawlersResponse:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            items:
              type: array
              description: Crawlers.
              items:
                title: crawlerResponse
                type: object
                properties:
                  id:
                    $ref: '#/components/schemas/CrawlerID'
                  name:
                    $ref: '#/components/schemas/CrawlerName'
    cache:
      type: object
      description: >
        Whether the crawler should cache crawled pages.


        For more information, see the [`cache`
        documentation](https://www.algolia.com/doc/tools/crawler/apis/configuration/cache/).
      properties:
        enabled:
          type: boolean
          default: true
          description: Whether the crawler cache is active.
    urlPattern:
      type: string
      description: >
        Pattern for matching URLs.


        Uses [micromatch](https://github.com/micromatch/micromatch) for
        negation, wildcards, and more.
      example: https://www.algolia.com/**
    fileTypes:
      type: string
      description: >
        Supported file type for indexing non-HTML documents.


        For more information, see [Extract data from non-HTML
        documents](https://www.algolia.com/doc/tools/crawler/extracting-data/non-html-documents/).
      enum:
        - doc
        - email
        - html
        - odp
        - ods
        - odt
        - pdf
        - ppt
        - xls
    hostnameAliases:
      type: object
      example:
        dev.example.com: example.com
      description: >
        Key-value pairs to replace matching hostnames found in a sitemap,

        on a page, in canonical links, or redirects.


        For more information, see the [`hostnameAliases`
        documentation](https://www.algolia.com/doc/tools/crawler/apis/configuration/hostname-aliases/).
      additionalProperties:
        type: string
        description: Hostname that should be added in the records.
        x-additionalPropertiesName: hostname
    pathAliases:
      type: object
      example:
        example.com:
          /foo: /bar
      description: >
        Key-value pairs to replace matching paths with new values.


        It doesn't replace:
          
        - URLs in the `startUrls`, `sitemaps`, `pathsToMatch`, and other
        settings.

        - Paths found in extracted text.


        The crawl continues from the _transformed_ URLs.
      additionalProperties:
        type: object
        description: Hostname for which matching paths should be replaced.
        x-additionalPropertiesName: hostname
        additionalProperties:
          type: string
          description: Key-value pair of a path that should be replaced.
          x-additionalPropertiesName: path
    configurationRecordExtractorType:
      type: string
      enum:
        - function
    Action:
      type: object
      description: |
        How to process crawled URLs.

        Each action defines:

        - The targeted subset of URLs it processes.
        - What information to extract from the web pages.
        - The Algolia indices where the extracted records will be stored.

        If a single web page matches several actions,
        one record is generated for each action.
      properties:
        autoGenerateObjectIDs:
          type: boolean
          description: Whether to generate an `objectID` for records that don't have one.
          default: true
        cache:
          $ref: '#/components/schemas/cache'
        discoveryPatterns:
          type: array
          description: >
            Indicates additional pages that the crawler should visit.


            For more information, see the [`discoveryPatterns`
            documentation](https://www.algolia.com/doc/tools/crawler/apis/configuration/discovery-patterns/).
          items:
            $ref: '#/components/schemas/urlPattern'
        fileTypesToMatch:
          type: array
          description: >
            File types for crawling non-HTML documents.


            For more information, see [Extract data from non-HTML
            documents](https://www.algolia.com/doc/tools/crawler/extracting-data/non-html-documents/).
          maxItems: 100
          items:
            $ref: '#/components/schemas/fileTypes'
          default:
            - html
          example:
            - html
            - pdf
        hostnameAliases:
          $ref: '#/components/schemas/hostnameAliases'
        indexName:
          type: string
          maxLength: 256
          description: >
            Reference to the index used to store the action's extracted records.

            `indexName` is combined with the prefix you specified in
            `indexPrefix`.
          example: algolia_website
        name:
          type: string
          description: >-
            Unique identifier for the action. This option is required if
            `schedule` is set.
        pathAliases:
          $ref: '#/components/schemas/pathAliases'
        pathsToMatch:
          type: array
          description: >
            URLs to which this action should apply.


            Uses [micromatch](https://github.com/micromatch/micromatch) for
            negation, wildcards, and more.
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/urlPattern'
        recordExtractor:
          title: recordExtractor
          type: object
          description: >
            Function for extracting information from a crawled page and
            transforming it into Algolia records for indexing.

            The Crawler has an
            [editor](https://www.algolia.com/doc/tools/crawler/getting-started/crawler-configuration/#the-editor)
            with autocomplete and validation to help you update the
            `recordExtractor` property.


            For details, consult the [`recordExtractor`
            documentation](https://www.algolia.com/doc/tools/crawler/apis/configuration/actions/#parameter-param-recordextractor).
          properties:
            __type:
              $ref: '#/components/schemas/configurationRecordExtractorType'
            source:
              type: string
              description: >
                A JavaScript function (as a string) that returns one or more
                Algolia records for each crawled page.
        selectorsToMatch:
          type: array
          description: >
            DOM selectors for nodes that must be present on the page to be
            processed.

            If the page doesn't match any of the selectors, it's ignored.
          maxItems: 100
          items:
            type: string
            description: >-
              DOM selector. Negation is supported. This lets you ignore pages
              that match the selector.
          example:
            - .products
            - '!.featured'
      required:
        - indexName
        - recordExtractor
    ignoreCanonicalTo:
      oneOf:
        - type: boolean
          description: |
            Whether to ignore canonical redirects.

            If true, canonical URLs for pages are ignored.
        - type: array
          description: |
            Canonical URLs or URL patterns to ignore.
          items:
            type: string
            description: |
              Pattern or URL.

              Canonical URLs are only ignored if they match this pattern.
    supportedLanguage:
      type: string
      description: ISO code for a supported language.
      enum:
        - af
        - ar
        - az
        - bg
        - bn
        - ca
        - cs
        - cy
        - da
        - de
        - el
        - en
        - eo
        - es
        - et
        - eu
        - fa
        - fi
        - fo
        - fr
        - ga
        - gl
        - he
        - hi
        - hu
        - hy
        - id
        - is
        - it
        - ja
        - ka
        - kk
        - ko
        - ku
        - ky
        - lt
        - lv
        - mi
        - mn
        - mr
        - ms
        - mt
        - nb
        - nl
        - 'no'
        - ns
        - pl
        - ps
        - pt
        - pt-br
        - qu
        - ro
        - ru
        - sk
        - sq
        - sv
        - sw
        - ta
        - te
        - th
        - tl
        - tn
        - tr
        - tt
        - uk
        - ur
        - uz
        - zh
    userData:
      type: object
      example:
        settingID: f2a7b51e3503acc6a39b3784ffb84300
        pluginVersion: 1.6.0
      description: |
        An object with custom data.

        You can store up to 32kB as custom data.
      default: {}
      x-categories:
        - Advanced
    maxFacetHits:
      type: integer
      description: >-
        Maximum number of facet values to return when [searching for facet
        values](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/#search-for-facet-values).
      maximum: 100
      default: 10
      x-categories:
        - Advanced
    baseIndexSettings:
      type: object
      additionalProperties: false
      properties:
        attributesForFaceting:
          type: array
          items:
            type: string
          example:
            - author
            - filterOnly(isbn)
            - searchable(edition)
            - afterDistinct(category)
            - afterDistinct(searchable(publisher))
          description: >
            Attributes used for
            [faceting](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/).


            Facets are attributes that let you categorize search results.

            They can be used for filtering search results.

            By default, no attribute is used for faceting.

            Attribute names are case-sensitive.


            **Modifiers**


            - `filterOnly("ATTRIBUTE")`.
              Allows the attribute to be used as a filter but doesn't evaluate the facet values.

            - `searchable("ATTRIBUTE")`.
              Allows searching for facet values.

            - `afterDistinct("ATTRIBUTE")`.
              Evaluates the facet count _after_ deduplication with `distinct`.
              This ensures accurate facet counts.
              You can apply this modifier to searchable facets: `afterDistinct(searchable(ATTRIBUTE))`.
          default: []
          x-categories:
            - Faceting
        replicas:
          type: array
          items:
            type: string
          example:
            - virtual(prod_products_price_asc)
            - dev_products_replica
          description: >
            Creates [replica
            indices](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/in-depth/replicas/).


            Replicas are copies of a primary index with the same records but
            different settings, synonyms, or rules.

            If you want to offer a different ranking or sorting of your search
            results, you'll use replica indices.

            All index operations on a primary index are automatically forwarded
            to its replicas.

            To add a replica index, you must provide the complete set of
            replicas to this parameter.

            If you omit a replica from this list, the replica turns into a
            regular, standalone index that will no longer be synced with the
            primary index.


            **Modifier**


            - `virtual("REPLICA")`.
              Create a virtual replica,
              Virtual replicas don't increase the number of records and are optimized for [Relevant sorting](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/in-depth/relevant-sort/).
          default: []
          x-categories:
            - Ranking
        paginationLimitedTo:
          type: integer
          example: 100
          description: >
            Maximum number of search results that can be obtained through
            pagination.


            Higher pagination limits might slow down your search.

            For pagination limits above 1,000, the sorting of results beyond the
            1,000th hit can't be guaranteed.
          default: 1000
          maximum: 20000
        unretrievableAttributes:
          type: array
          items:
            type: string
          example:
            - total_sales
          description: >
            Attributes that can't be retrieved at query time.


            This can be useful if you want to use an attribute for ranking or to
            [restrict
            access](https://www.algolia.com/doc/guides/security/api-keys/how-to/user-restricted-access-to-data/),

            but don't want to include it in the search results.

            Attribute names are case-sensitive.
          default: []
          x-categories:
            - Attributes
        disableTypoToleranceOnWords:
          type: array
          items:
            type: string
          example:
            - wheel
            - 1X2BCD
          description: >
            Creates a list of [words which require exact
            matches](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/in-depth/configuring-typo-tolerance/#turn-off-typo-tolerance-for-certain-words).

            This also turns off [word splitting and
            concatenation](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/splitting-and-concatenation/)
            for the specified words.
          default: []
          x-categories:
            - Typos
        attributesToTransliterate:
          description: >
            Attributes, for which you want to support [Japanese
            transliteration](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/language-specific-configurations/#japanese-transliteration-and-type-ahead).


            Transliteration supports searching in any of the Japanese writing
            systems.

            To support transliteration, you must set the indexing language to
            Japanese.

            Attribute names are case-sensitive.
          type: array
          items:
            type: string
          example:
            - name
            - description
          x-categories:
            - Languages
        camelCaseAttributes:
          type: array
          items:
            type: string
          example:
            - description
          description: >
            Attributes for which to split [camel
            case](https://wikipedia.org/wiki/Camel_case) words.

            Attribute names are case-sensitive.
          default: []
          x-categories:
            - Languages
        decompoundedAttributes:
          type: object
          example:
            de:
              - name
          description: >
            Searchable attributes to which Algolia should apply [word
            segmentation](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-segmentation/)
            (decompounding).

            Attribute names are case-sensitive.


            Compound words are formed by combining two or more individual words,

            and are particularly prevalent in Germanic languagesfor example,
            "firefighter".

            With decompounding, the individual components are indexed
            separately.


            You can specify different lists for different languages.

            Decompounding is supported for these languages:

            Dutch (`nl`), German (`de`), Finnish (`fi`), Danish (`da`), Swedish
            (`sv`), and Norwegian (`no`).

            Decompounding doesn't work for words with [non-spacing mark Unicode
            characters](https://www.charactercodes.net/category/non-spacing_mark).

            For example, `Gartenst�hle` won't be decompounded if the `�`
            consists of `u` (U+0075) and `�` (U+0308).
          default: {}
          x-categories:
            - Languages
        indexLanguages:
          type: array
          items:
            $ref: '#/components/schemas/supportedLanguage'
          example:
            - ja
          description: >
            Languages for language-specific processing steps, such as word
            detection and dictionary settings.


            **You should always specify an indexing language.**

            If you don't specify an indexing language, the search engine uses
            all [supported
            languages](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/),

            or the languages you specified with the `ignorePlurals` or
            `removeStopWords` parameters.

            This can lead to unexpected search results.

            For more information, see [Language-specific
            configuration](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/language-specific-configurations/).
          default: []
          x-categories:
            - Languages
        disablePrefixOnAttributes:
          type: array
          items:
            type: string
          example:
            - sku
          description: >
            Searchable attributes for which you want to turn off [prefix
            matching](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/#adjusting-prefix-search).

            Attribute names are case-sensitive.
          default: []
          x-categories:
            - Query strategy
        allowCompressionOfIntegerArray:
          type: boolean
          description: >
            Whether arrays with exclusively non-negative integers should be
            compressed for better performance.

            If true, the compressed arrays may be reordered.
          default: false
          x-categories:
            - Performance
        numericAttributesForFiltering:
          type: array
          items:
            type: string
          description: >
            Numeric attributes that can be used as [numerical
            filters](https://www.algolia.com/doc/guides/managing-results/rules/detecting-intent/how-to/applying-a-custom-filter-for-a-specific-query/#numerical-filters).

            Attribute names are case-sensitive.


            By default, all numeric attributes are available as numerical
            filters.

            For faster indexing, reduce the number of numeric attributes.


            To turn off filtering for all numeric attributes, specify an
            attribute that doesn't exist in your index, such as
            `NO_NUMERIC_FILTERING`.


            **Modifier**


            - `equalOnly("ATTRIBUTE")`.
              Support only filtering based on equality comparisons `=` and `!=`.
          example:
            - equalOnly(quantity)
            - popularity
          default: []
          x-categories:
            - Performance
        separatorsToIndex:
          type: string
          example: +#
          description: >
            Control which non-alphanumeric characters are indexed.


            By default, Algolia ignores [non-alphanumeric
            characters](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/how-to/how-to-search-in-hyphenated-attributes/#handling-non-alphanumeric-characters)
            like hyphen (`-`), plus (`+`), and parentheses (`(`,`)`).

            To include such characters, define them with `separatorsToIndex`.


            Separators are all non-letter characters except spaces and currency
            characters, such as $���.


            With `separatorsToIndex`, Algolia treats separator characters as
            separate words.

            For example, in a search for "Disney+", Algolia considers "Disney"
            and "+" as two separate words.
          default: ''
          x-categories:
            - Typos
        searchableAttributes:
          type: array
          items:
            type: string
          example:
            - title,alternative_title
            - author
            - unordered(text)
            - emails.personal
          description: >
            Attributes used for searching. Attribute names are case-sensitive.


            By default, all attributes are searchable and the
            [Attribute](https://www.algolia.com/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria/#attribute)
            ranking criterion is turned off.

            With a non-empty list, Algolia only returns results with matches in
            the selected attributes.

            In addition, the Attribute ranking criterion is turned on: matches
            in attributes that are higher in the list of `searchableAttributes`
            rank first.

            To make matches in two attributes rank equally, include them in a
            comma-separated string, such as `"title,alternate_title"`.

            Attributes with the same priority are always unordered.


            For more information, see [Searchable
            attributes](https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data/how-to/setting-searchable-attributes/).


            **Modifier**


            - `unordered("ATTRIBUTE")`.
              Ignore the position of a match within the attribute.

            Without a modifier, matches at the beginning of an attribute rank
            higher than matches at the end.
          default: []
          x-categories:
            - Attributes
        userData:
          $ref: '#/components/schemas/userData'
        customNormalization:
          description: >
            Characters and their normalized replacements.

            This overrides Algolia's default
            [normalization](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/normalization/).
          type: object
          example:
            default:
              �: ae
              �: ue
          additionalProperties:
            type: object
            additionalProperties:
              type: string
          x-categories:
            - Languages
        attributeForDistinct:
          description: >
            Attribute that should be used to establish groups of results.

            Attribute names are case-sensitive.


            All records with the same value for this attribute are considered a
            group.

            You can combine `attributeForDistinct` with the `distinct` search
            parameter to control

            how many items per group are included in the search results.


            If you want to use the same attribute also for faceting, use the
            `afterDistinct` modifier of the `attributesForFaceting` setting.

            This applies faceting _after_ deduplication, which will result in
            accurate facet counts.
          example: url
          type: string
        maxFacetHits:
          $ref: '#/components/schemas/maxFacetHits'
        keepDiacriticsOnCharacters:
          type: string
          example: ��
          description: |
            Characters for which diacritics should be preserved.

            By default, Algolia removes diacritics from letters.
            For example, `�` becomes `e`. If this causes issues in your search,
            you can specify characters that should keep their diacritics.
          default: ''
          x-categories:
            - Languages
        customRanking:
          type: array
          items:
            type: string
          example:
            - desc(popularity)
            - asc(price)
          description: >
            Attributes to use as [custom
            ranking](https://www.algolia.com/doc/guides/managing-results/must-do/custom-ranking/).

            Attribute names are case-sensitive.


            The custom ranking attributes decide which items are shown first if
            the other ranking criteria are equal.


            Records with missing values for your selected custom ranking
            attributes are always sorted last.

            Boolean attributes are sorted based on their alphabetical order.


            **Modifiers**


            - `asc("ATTRIBUTE")`.
              Sort the index by the values of an attribute, in ascending order.

            - `desc("ATTRIBUTE")`.
              Sort the index by the values of an attribute, in descending order.

            If you use two or more custom ranking attributes,

            [reduce the
            precision](https://www.algolia.com/doc/guides/managing-results/must-do/custom-ranking/how-to/controlling-custom-ranking-metrics-precision/)
            of your first attributes,

            or the other attributes will never be applied.
          default: []
          x-categories:
            - Ranking
    hitsPerPage:
      type: integer
      description: Number of hits per page.
      default: 20
      minimum: 1
      maximum: 1000
      x-categories:
        - Pagination
    typoToleranceEnum:
      type: string
      title: typo tolerance
      description: |
        - `min`. Return matches with the lowest number of typos.
          For example, if you have matches without typos, only include those.
          But if there are no matches without typos (with 1 typo), include matches with 1 typo (2 typos).
        - `strict`. Return matches with the two lowest numbers of typos.
          With `strict`, the Typo ranking criterion is applied first in the `ranking` setting.
      enum:
        - min
        - strict
    typoTolerance:
      description: >
        Whether [typo
        tolerance](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/)
        is enabled and how it is applied.


        If typo tolerance is true, `min`, or `strict`, [word splitting and
        concatenation](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/splitting-and-concatenation/)
        are also active.
      oneOf:
        - type: boolean
          default: true
          description: >-
            Whether typo tolerance is active. If true, matches with typos are
            included in the search results and rank after exact matches.
        - $ref: '#/components/schemas/typoToleranceEnum'
      x-categories:
        - Typos
    booleanString:
      type: string
      enum:
        - 'true'
        - 'false'
    ignorePlurals:
      description: |
        Treat singular, plurals, and other forms of declensions as equivalent.
        You should only use this feature for the languages used in your index.
      example:
        - ca
        - es
      oneOf:
        - type: array
          description: |
            ISO code for languages for which this feature should be active.
            This overrides languages you set with `queryLanguages`.
          items:
            $ref: '#/components/schemas/supportedLanguage'
        - $ref: '#/components/schemas/booleanString'
        - type: boolean
          description: >
            If true, `ignorePlurals` is active for all languages included in
            `queryLanguages`, or for all supported languages, if `queryLanguges`
            is empty.

            If false, singulars, plurals, and other declensions won't be
            considered equivalent.
          default: false
      x-categories:
        - Languages
    removeStopWords:
      description: >
        Removes stop words from the search query.


        Stop words are common words like articles, conjunctions, prepositions,
        or pronouns that have little or no meaning on their own.

        In English, "the", "a", or "and" are stop words.


        You should only use this feature for the languages used in your index.
      example:
        - ca
        - es
      oneOf:
        - type: array
          description: >-
            ISO code for languages for which stop words should be removed. This
            overrides languages you set in `queryLanguges`.
          items:
            $ref: '#/components/schemas/supportedLanguage'
        - type: boolean
          default: false
          description: >
            If true, stop words are removed for all languages you included in
            `queryLanguages`, or for all supported languages, if
            `queryLanguages` is empty.

            If false, stop words are not removed.
      x-categories:
        - Languages
    queryType:
      type: string
      enum:
        - prefixLast
        - prefixAll
        - prefixNone
      description: >
        Determines if and how query words are interpreted as prefixes.


        By default, only the last query word is treated as a prefix
        (`prefixLast`).

        To turn off prefix search, use `prefixNone`.

        Avoid `prefixAll`, which treats all query words as prefixes.

        This might lead to counterintuitive results and makes your search
        slower.


        For more information, see [Prefix
        searching](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/in-depth/prefix-searching/).
      default: prefixLast
      x-categories:
        - Query strategy
    removeWordsIfNoResults:
      type: string
      enum:
        - none
        - lastWords
        - firstWords
        - allOptional
      example: firstWords
      description: >
        Strategy for removing words from the query when it doesn't return any
        results.

        This helps to avoid returning empty search results.


        - `none`.
          No words are removed when a query doesn't return results.

        - `lastWords`.
          Treat the last (then second to last, then third to last) word as optional,
          until there are results or at most 5 words have been removed.

        - `firstWords`.
          Treat the first (then second, then third) word as optional,
          until there are results or at most 5 words have been removed.

        - `allOptional`.
          Treat all words as optional.

        For more information, see [Remove words to improve
        results](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/empty-or-insufficient-results/in-depth/why-use-remove-words-if-no-results/).
      default: none
      x-categories:
        - Query strategy
    mode:
      type: string
      enum:
        - neuralSearch
        - keywordSearch
      description: >
        Search mode the index will use to query for results.


        This setting only applies to indices, for which Algolia enabled
        NeuralSearch for you.
      default: keywordSearch
      x-categories:
        - Query strategy
    semanticSearch:
      type: object
      description: |
        Settings for the semantic search part of NeuralSearch.
        Only used when `mode` is `neuralSearch`.
      properties:
        eventSources:
          oneOf:
            - type: array
              description: |
                Indices from which to collect click and conversion events.

                If null, the current index and all its replicas are used.
              items:
                type: string
            - type: 'null'
    optionalWordsArray:
      type: array
      items:
        type: string
      example:
        - blue
        - iphone case
      description: >
        Words that should be considered optional when found in the query.


        By default, records must match all words in the search query to be
        included in the search results.

        Adding optional words can help to increase the number of search results
        by running an additional search query that doesn't include the optional
        words.

        For example, if the search query is "action video" and "video" is an
        optional word,

        the search engine runs two queries. One for "action video" and one for
        "action".

        Records that match all words are ranked higher.


        For a search query with 4 or more words **and** all its words are
        optional,

        the number of matched words required for a record to be included in the
        search results increases for every 1,000 records:


        - If `optionalWords` has less than 10 words, the required number of
        matched words increases by 1:
          results 1 to 1,000 require 1 matched word, results 1,001 to 2000 need 2 matched words.
        - If `optionalWords` has 10 or more words, the number of required
        matched words increases by the number of optional words divided by 5
        (rounded down).
          For example, with 18 optional words: results 1 to 1,000 require 1 matched word, results 1,001 to 2000 need 4 matched words.

        For more information, see [Optional
        words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/empty-or-insufficient-results/#creating-a-list-of-optional-words).
      default: []
      x-categories:
        - Query strategy
    optionalWords:
      oneOf:
        - type: string
        - type: 'null'
        - $ref: '#/components/schemas/optionalWordsArray'
    exactOnSingleWordQuery:
      type: string
      enum:
        - attribute
        - none
        - word
      description: >
        Determines how the [Exact ranking
        criterion](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/in-depth/adjust-exact-settings/#turn-off-exact-for-some-attributes)
        is computed when the search query has only one word.


        - `attribute`.
          The Exact ranking criterion is 1 if the query word and attribute value are the same.
          For example, a search for "road" will match the value "road", but not "road trip".

        - `none`.
          The Exact ranking criterion is ignored on single-word searches.

        - `word`.
          The Exact ranking criterion is 1 if the query word is found in the attribute value.
          The query word must have at least 3 characters and must not be a stop word.
          Only exact matches will be highlighted,
          partial and prefix matches won't.
      default: attribute
      x-categories:
        - Query strategy
    alternativesAsExact:
      type: string
      enum:
        - ignorePlurals
        - singleWordSynonym
        - multiWordsSynonym
        - ignoreConjugations
      x-categories:
        - Query strategy
    advancedSyntaxFeatures:
      type: string
      enum:
        - exactPhrase
        - excludeWords
      x-categories:
        - Query strategy
    distinct:
      description: >
        Determines how many records of a group are included in the search
        results.


        Records with the same value for the `attributeForDistinct` attribute are
        considered a group.

        The `distinct` setting controls how many members of the group are
        returned.

        This is useful for [deduplication and
        grouping](https://www.algolia.com/doc/guides/managing-results/refine-results/grouping/#introducing-algolias-distinct-feature).


        The `distinct` setting is ignored if `attributeForDistinct` is not set.
      example: 1
      oneOf:
        - type: boolean
          description: >-
            Whether deduplication is turned on. If true, only one member of a
            group is shown in the search results.
        - type: integer
          description: >
            Number of members of a group of records to include in the search
            results.


            - Don't use `distinct > 1` for records that might be [promoted by
            rules](https://www.algolia.com/doc/guides/managing-results/rules/merchandising-and-promoting/how-to/promote-hits/).
              The number of hits won't be correct and faceting won't work as expected.
            - With `distinct > 1`, the `hitsPerPage` parameter controls the
            number of returned groups.
              For example, with `hitsPerPage: 10` and `distinct: 2`, up to 20 records are returned.
              Likewise, the `nbHits` response attribute contains the number of returned groups.
          minimum: 0
          maximum: 4
          default: 0
      x-categories:
        - Advanced
    order:
      description: >
        Explicit order of facets or facet values.


        This setting lets you always show specific facets or facet values at the
        top of the list.
      type: array
      items:
        type: string
    facets:
      description: Order of facet names.
      type: object
      additionalProperties: false
      properties:
        order:
          $ref: '#/components/schemas/order'
    sortRemainingBy:
      description: >
        Order of facet values that aren't explicitly positioned with the `order`
        setting.


        - `count`.
          Order remaining facet values by decreasing count.
          The count is the number of matching records containing this facet value.

        - `alpha`.
          Sort facet values alphabetically.

        - `hidden`.
          Don't show facet values that aren't explicitly positioned.
      type: string
      enum:
        - count
        - alpha
        - hidden
    hide:
      description: Hide facet values.
      type: array
      items:
        type: string
    value:
      type: object
      additionalProperties: false
      properties:
        order:
          $ref: '#/components/schemas/order'
        sortRemainingBy:
          $ref: '#/components/schemas/sortRemainingBy'
        hide:
          $ref: '#/components/schemas/hide'
    values:
      description: Order of facet values. One object for each facet.
      type: object
      additionalProperties:
        x-additionalPropertiesName: facet
        $ref: '#/components/schemas/value'
    facetOrdering:
      description: Order of facet names and facet values in your UI.
      type: object
      additionalProperties: false
      properties:
        facets:
          $ref: '#/components/schemas/facets'
        values:
          $ref: '#/components/schemas/values'
    redirectURL:
      description: The redirect rule container.
      type: object
      additionalProperties: false
      properties:
        url:
          type: string
    bannerImageUrl:
      description: URL for an image to show inside a banner.
      type: object
      additionalProperties: false
      properties:
        url:
          type: string
    bannerImage:
      description: Image to show inside a banner.
      type: object
      additionalProperties: false
      properties:
        urls:
          type: array
          items:
            $ref: '#/components/schemas/bannerImageUrl'
        title:
          type: string
    bannerLink:
      description: Link for a banner defined in the Merchandising Studio.
      type: object
      additionalProperties: false
      properties:
        url:
          type: string
    banner:
      description: Banner with image and link to redirect users.
      type: object
      additionalProperties: false
      properties:
        image:
          $ref: '#/components/schemas/bannerImage'
        link:
          $ref: '#/components/schemas/bannerLink'
    banners:
      description: Banners defined in the Merchandising Studio for a given search.
      type: array
      items:
        $ref: '#/components/schemas/banner'
    widgets:
      description: Widgets returned from any rules that are applied to the current search.
      type: object
      additionalProperties: false
      properties:
        banners:
          $ref: '#/components/schemas/banners'
    renderingContent:
      description: >
        Extra data that can be used in the search UI.


        You can use this to control aspects of your search UI, such as the order
        of facet names and values

        without changing your frontend code.
      type: object
      additionalProperties: false
      properties:
        facetOrdering:
          $ref: '#/components/schemas/facetOrdering'
        redirect:
          $ref: '#/components/schemas/redirectURL'
        widgets:
          $ref: '#/components/schemas/widgets'
      x-categories:
        - Advanced
    reRankingApplyFilter:
      description: >
        Restrict [Dynamic
        Re-Ranking](https://www.algolia.com/doc/guides/algolia-ai/re-ranking/)
        to records that match these filters.
      oneOf:
        - type: array
          items:
            $ref: '#/components/schemas/reRankingApplyFilter'
        - type: string
          x-categories:
            - Filtering
    indexSettingsAsSearchParams:
      type: object
      additionalProperties: false
      properties:
        attributesToRetrieve:
          type: array
          items:
            type: string
          example:
            - author
            - title
            - content
          description: >
            Attributes to include in the API response.


            To reduce the size of your response, you can retrieve only some of
            the attributes.

            Attribute names are case-sensitive.


            - `*` retrieves all attributes, except attributes included in the
            `customRanking` and `unretrievableAttributes` settings.

            - To retrieve all attributes except a specific one, prefix the
            attribute with a dash and combine it with the `*`: `["*",
            "-ATTRIBUTE"]`.

            - The `objectID` attribute is always included.
          default:
            - '*'
          x-categories:
            - Attributes
        ranking:
          type: array
          items:
            type: string
          description: >
            Determines the order in which Algolia returns your results.


            By default, each entry corresponds to a [ranking
            criteria](https://www.algolia.com/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria/).

            The tie-breaking algorithm sequentially applies each criterion in
            the order they're specified.

            If you configure a replica index for [sorting by an
            attribute](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/how-to/sort-by-attribute/),

            you put the sorting attribute at the top of the list.


            **Modifiers**


            - `asc("ATTRIBUTE")`.
              Sort the index by the values of an attribute, in ascending order.
            - `desc("ATTRIBUTE")`.
              Sort the index by the values of an attribute, in descending order.

            Before you modify the default setting,

            you should test your changes in the dashboard,

            and by [A/B
            testing](https://www.algolia.com/doc/guides/ab-testing/what-is-ab-testing/).
          default:
            - typo
            - geo
            - words
            - filters
            - proximity
            - attribute
            - exact
            - custom
          x-categories:
            - Ranking
        relevancyStrictness:
          type: integer
          example: 90
          description: >
            Relevancy threshold below which less relevant results aren't
            included in the results.


            You can only set `relevancyStrictness` on [virtual replica
            indices](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/in-depth/replicas/#what-are-virtual-replicas).

            Use this setting to strike a balance between the relevance and
            number of returned results.
          default: 100
          x-categories:
            - Ranking
        attributesToHighlight:
          type: array
          items:
            type: string
          example:
            - author
            - title
            - conten
            - content
          description: >
            Attributes to highlight.


            By default, all searchable attributes are highlighted.

            Use `*` to highlight all attributes or use an empty array `[]` to
            turn off highlighting.

            Attribute names are case-sensitive.


            With highlighting, strings that match the search query are
            surrounded by HTML tags defined by `highlightPreTag` and
            `highlightPostTag`.

            You can use this to visually highlight matching parts of a search
            query in your UI.


            For more information, see [Highlighting and
            snippeting](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/highlighting-snippeting/js/).
          x-categories:
            - Highlighting and Snippeting
        attributesToSnippet:
          type: array
          items:
            type: string
          example:
            - content:80
            - description
          description: >
            Attributes for which to enable snippets.

            Attribute names are case-sensitive.


            Snippets provide additional context to matched words.

            If you enable snippets, they include 10 words, including the matched
            word.

            The matched word will also be wrapped by HTML tags for highlighting.

            You can adjust the number of words with the following notation:
            `ATTRIBUTE:NUMBER`,

            where `NUMBER` is the number of words to be extracted.
          default: []
          x-categories:
            - Highlighting and Snippeting
        highlightPreTag:
          type: string
          description: >-
            HTML tag to insert before the highlighted parts in all highlighted
            results and snippets.
          default: <em>
          x-categories:
            - Highlighting and Snippeting
        highlightPostTag:
          type: string
          description: >-
            HTML tag to insert after the highlighted parts in all highlighted
            results and snippets.
          default: </em>
          x-categories:
            - Highlighting and Snippeting
        snippetEllipsisText:
          type: string
          description: String used as an ellipsis indicator when a snippet is truncated.
          default: &
          x-categories:
            - Highlighting and Snippeting
        restrictHighlightAndSnippetArrays:
          type: boolean
          description: >
            Whether to restrict highlighting and snippeting to items that at
            least partially matched the search query.

            By default, all items are highlighted and snippeted.
          default: false
          x-categories:
            - Highlighting and Snippeting
        hitsPerPage:
          $ref: '#/components/schemas/hitsPerPage'
        minWordSizefor1Typo:
          type: integer
          description: >-
            Minimum number of characters a word in the search query must contain
            to accept matches with [one
            typo](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/in-depth/configuring-typo-tolerance/#configuring-word-length-for-typos).
          default: 4
          x-categories:
            - Typos
        minWordSizefor2Typos:
          type: integer
          description: >-
            Minimum number of characters a word in the search query must contain
            to accept matches with [two
            typos](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/in-depth/configuring-typo-tolerance/#configuring-word-length-for-typos).
          default: 8
          x-categories:
            - Typos
        typoTolerance:
          $ref: '#/components/schemas/typoTolerance'
        allowTyposOnNumericTokens:
          type: boolean
          description: |
            Whether to allow typos on numbers in the search query.

            Turn off this setting to reduce the number of irrelevant matches
            when searching in large sets of similar numbers.
          default: true
          x-categories:
            - Typos
        disableTypoToleranceOnAttributes:
          type: array
          items:
            type: string
          example:
            - sku
          description: >
            Attributes for which you want to turn off [typo
            tolerance](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/).

            Attribute names are case-sensitive.


            Returning only exact matches can help when:


            - [Searching in hyphenated
            attributes](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/how-to/how-to-search-in-hyphenated-attributes/).

            - Reducing the number of matches when you have too many.
              This can happen with attributes that are long blocks of text, such as product descriptions.

            Consider alternatives such as `disableTypoToleranceOnWords` or
            adding synonyms if your attributes have intentional unusual
            spellings that might look like typos.
          default: []
          x-categories:
            - Typos
        ignorePlurals:
          $ref: '#/components/schemas/ignorePlurals'
        removeStopWords:
          $ref: '#/components/schemas/removeStopWords'
        queryLanguages:
          type: array
          items:
            $ref: '#/components/schemas/supportedLanguage'
          example:
            - es
          description: >
            Languages for language-specific query processing steps such as
            plurals, stop-word removal, and word-detection dictionaries.


            This setting sets a default list of languages used by the
            `removeStopWords` and `ignorePlurals` settings.

            This setting also sets a dictionary for word detection in the
            logogram-based
            [CJK](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/normalization/#normalization-for-logogram-based-languages-cjk)
            languages.

            To support this, you must place the CJK language **first**.


            **You should always specify a query language.**

            If you don't specify an indexing language, the search engine uses
            all [supported
            languages](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/),

            or the languages you specified with the `ignorePlurals` or
            `removeStopWords` parameters.

            This can lead to unexpected search results.

            For more information, see [Language-specific
            configuration](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/language-specific-configurations/).
          default: []
          x-categories:
            - Languages
        decompoundQuery:
          type: boolean
          description: >
            Whether to split compound words in the query into their building
            blocks.


            For more information, see [Word
            segmentation](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/language-specific-configurations/#splitting-compound-words).

            Word segmentation is supported for these languages: German, Dutch,
            Finnish, Swedish, and Norwegian.

            Decompounding doesn't work for words with [non-spacing mark Unicode
            characters](https://www.charactercodes.net/category/non-spacing_mark).

            For example, `Gartenst�hle` won't be decompounded if the `�`
            consists of `u` (U+0075) and `�` (U+0308).
          default: true
          x-categories:
            - Languages
        enableRules:
          type: boolean
          description: Whether to enable rules.
          default: true
          x-categories:
            - Rules
        enablePersonalization:
          type: boolean
          description: Whether to enable Personalization.
          default: false
          x-categories:
            - Personalization
        queryType:
          $ref: '#/components/schemas/queryType'
        removeWordsIfNoResults:
          $ref: '#/components/schemas/removeWordsIfNoResults'
        mode:
          $ref: '#/components/schemas/mode'
        semanticSearch:
          $ref: '#/components/schemas/semanticSearch'
        advancedSyntax:
          type: boolean
          description: >
            Whether to support phrase matching and excluding words from search
            queries.


            Use the `advancedSyntaxFeatures` parameter to control which feature
            is supported.
          default: false
          x-categories:
            - Query strategy
        optionalWords:
          $ref: '#/components/schemas/optionalWords'
        disableExactOnAttributes:
          type: array
          items:
            type: string
          example:
            - description
          description: >
            Searchable attributes for which you want to [turn off the Exact
            ranking
            criterion](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/in-depth/adjust-exact-settings/#turn-off-exact-for-some-attributes).

            Attribute names are case-sensitive.


            This can be useful for attributes with long values, where the
            likelihood of an exact match is high,

            such as product descriptions.

            Turning off the Exact ranking criterion for these attributes favors
            exact matching on other attributes.

            This reduces the impact of individual attributes with a lot of
            content on ranking.
          default: []
          x-categories:
            - Query strategy
        exactOnSingleWordQuery:
          $ref: '#/components/schemas/exactOnSingleWordQuery'
        alternativesAsExact:
          type: array
          items:
            $ref: '#/components/schemas/alternativesAsExact'
          description: >
            Determine which plurals and synonyms should be considered an exact
            matches.


            By default, Algolia treats singular and plural forms of a word, and
            single-word synonyms, as
            [exact](https://www.algolia.com/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria/#exact)
            matches when searching.

            For example:


            - "swimsuit" and "swimsuits" are treated the same

            - "swimsuit" and "swimwear" are treated the same (if they are
            [synonyms](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms/#regular-synonyms)).


            - `ignorePlurals`.
              Plurals and similar declensions added by the `ignorePlurals` setting are considered exact matches.

            - `singleWordSynonym`.
              Single-word synonyms, such as "NY" = "NYC", are considered exact matches.

            - `multiWordsSynonym`.
              Multi-word synonyms, such as "NY" = "New York", are considered exact matches.
          default:
            - ignorePlurals
            - singleWordSynonym
          x-categories:
            - Query strategy
        advancedSyntaxFeatures:
          type: array
          items:
            $ref: '#/components/schemas/advancedSyntaxFeatures'
          description: |
            Advanced search syntax features you want to support.

            - `exactPhrase`.
              Phrases in quotes must match exactly.
              For example, `sparkly blue "iPhone case"` only returns records with the exact string "iPhone case".

            - `excludeWords`.
              Query words prefixed with a `-` must not occur in a record.
              For example, `search -engine` matches records that contain "search" but not "engine".

            This setting only has an effect if `advancedSyntax` is true.
          default:
            - exactPhrase
            - excludeWords
          x-categories:
            - Query strategy
        distinct:
          $ref: '#/components/schemas/distinct'
        replaceSynonymsInHighlight:
          type: boolean
          description: >
            Whether to replace a highlighted word with the matched synonym.


            By default, the original words are highlighted even if a synonym
            matches.

            For example, with `home` as a synonym for `house` and a search for
            `home`,

            records matching either "home" or "house" are included in the search
            results,

            and either "home" or "house" are highlighted.


            With `replaceSynonymsInHighlight` set to `true`, a search for `home`
            still matches the same records,

            but all occurrences of "house" are replaced by "home" in the
            highlighted response.
          default: false
          x-categories:
            - Highlighting and Snippeting
        minProximity:
          type: integer
          minimum: 1
          maximum: 7
          description: >
            Minimum proximity score for two matching words.


            This adjusts the [Proximity ranking
            criterion](https://www.algolia.com/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria/#proximity)

            by equally scoring matches that are farther apart.


            For example, if `minProximity` is 2, neighboring matches and matches
            with one word between them would have the same score.
          default: 1
          x-categories:
            - Advanced
        responseFields:
          type: array
          items:
            type: string
          description: >
            Properties to include in the API response of search and browse
            requests.


            By default, all response properties are included.

            To reduce the response size, you can select which properties should
            be included.


            An empty list may lead to an empty API response (except properties
            you can't exclude).


            You can't exclude these properties:

            `message`, `warning`, `cursor`, `abTestVariantID`,

            or any property added by setting `getRankingInfo` to true.


            Your search depends on the `hits` field. If you omit this field,
            searches won't return any results.

            Your UI might also depend on other properties, for example, for
            pagination.

            Before restricting the response size, check the impact on your
            search experience.
          default:
            - '*'
          x-categories:
            - Advanced
        maxValuesPerFacet:
          type: integer
          description: Maximum number of facet values to return for each facet.
          default: 100
          maximum: 1000
          x-categories:
            - Faceting
        sortFacetValuesBy:
          type: string
          description: >
            Order in which to retrieve facet values.


            - `count`.
              Facet values are retrieved by decreasing count.
              The count is the number of matching records containing this facet value.

            - `alpha`.
              Retrieve facet values alphabetically.

            This setting doesn't influence how facet values are displayed in
            your UI (see `renderingContent`).

            For more information, see [facet value
            display](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/facet-display/js/).
          default: count
          x-categories:
            - Faceting
        attributeCriteriaComputedByMinProximity:
          type: boolean
          description: >
            Whether the best matching attribute should be determined by minimum
            proximity.


            This setting only affects ranking if the Attribute ranking criterion
            comes before Proximity in the `ranking` setting.

            If true, the best matching attribute is selected based on the
            minimum proximity of multiple matches.

            Otherwise, the best matching attribute is determined by the order in
            the `searchableAttributes` setting.
          default: false
          x-categories:
            - Advanced
        renderingContent:
          $ref: '#/components/schemas/renderingContent'
        enableReRanking:
          type: boolean
          description: >
            Whether this search will use [Dynamic
            Re-Ranking](https://www.algolia.com/doc/guides/algolia-ai/re-ranking/).


            This setting only has an effect if you activated Dynamic Re-Ranking
            for this index in the Algolia dashboard.
          default: true
          x-categories:
            - Filtering
        reRankingApplyFilter:
          oneOf:
            - $ref: '#/components/schemas/reRankingApplyFilter'
            - type: 'null'
    indexSettings:
      description: Index settings.
      allOf:
        - $ref: '#/components/schemas/baseIndexSettings'
        - $ref: '#/components/schemas/indexSettingsAsSearchParams'
    headers:
      type: object
      description: Headers to add to all requests.
      properties:
        Accept-Language:
          type: string
          description: Preferred natural language and locale.
          example: fr-FR
        Authorization:
          type: string
          description: Basic authentication header.
          example: Bearer Aerehdf==
        Cookie:
          type: string
          description: >-
            Cookie. The header will be replaced by the cookie retrieved when
            logging in.
          example: session=1234
    loginRequestOptions:
      type: object
      description: Options for the HTTP request for logging in.
      properties:
        method:
          type: string
          description: HTTP method for sending the request.
          default: GET
          example: POST
        headers:
          $ref: '#/components/schemas/headers'
        body:
          type: string
          description: Form content.
          example: id=user&password=s3cr3t
        timeout:
          type: number
          description: Timeout for the request.
    fetchRequest:
      type: object
      description: Information for making a HTTP request for authorization.
      properties:
        url:
          type: string
          description: URL with your login form.
          example: https://example.com/login
        requestOptions:
          $ref: '#/components/schemas/loginRequestOptions'
      required:
        - url
    waitTime:
      type: object
      description: Timeout for the HTTP request.
      properties:
        min:
          type: number
          default: 0
          description: Minimum waiting time in milliseconds.
        max:
          type: number
          default: 20000
          description: Maximum waiting time in milliseconds.
    browserRequest:
      type: object
      description: |
        Information for using a web browser for authorization.
        The browser loads a login page and enters the provided credentials.
      properties:
        url:
          type: string
          description: >
            URL of your login page.


            The crawler looks for an input matching the selector
            `input[type=text]` or `input[type=email]` for the username and
            `input[type=password]` for the password.
          example: https://example.com/login
        username:
          type: string
          description: Username for signing in.
          example: crawler
        password:
          type: string
          description: Password for signing in.
          example: s3cr3t
        waitTime:
          $ref: '#/components/schemas/waitTime'
      required:
        - url
        - username
        - password
    grantType:
      type: string
      description: OAuth 2.0 grant type.
      enum:
        - client_credentials
    extraParameters:
      type: object
      description: Extra parameters for the authorization request.
      properties:
        resource:
          type: string
          description: >
            App ID URI of the receiving web service.


            For more information, see [Azure Active
            Directory](https://learn.microsoft.com/en-us/previous-versions/azure/active-directory/azuread-dev/v1-oauth2-client-creds-grant-flow#first-case-access-token-request-with-a-shared-secret).
    accessTokenRequest:
      type: object
      description: >
        Parameters required to make the [access token
        request](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4.2).
      properties:
        url:
          type: string
          description: URL for the access token endpoint.
        grantType:
          $ref: '#/components/schemas/grantType'
        clientId:
          type: string
          description: >
            [Client
            identifier](https://datatracker.ietf.org/doc/html/rfc6749#section-2.2).
        clientSecret:
          type: string
          description: Client secret.
        scope:
          type: string
          description: >
            [Access token
            scope](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3).
        extraParameters:
          $ref: '#/components/schemas/extraParameters'
      required:
        - url
        - grantType
        - clientId
        - clientSecret
    oauthRequest:
      type: object
      description: >
        Authorization information for using the [OAuth 2.0 client
        credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4)
        authorization grant.

        OAuth authorization is supported for [Azure Active Directory version
        1](https://learn.microsoft.com/en-us/previous-versions/azure/active-directory/azuread-dev/v1-oauth2-client-creds-grant-flow)
        as provider.
      properties:
        accessTokenRequest:
          $ref: '#/components/schemas/accessTokenRequest'
      required:
        - accessTokenRequest
    login:
      description: Authorization method and credentials for crawling protected content.
      oneOf:
        - $ref: '#/components/schemas/fetchRequest'
        - $ref: '#/components/schemas/browserRequest'
        - $ref: '#/components/schemas/oauthRequest'
    renderJavaScript:
      description: >
        Crawl JavaScript-rendered pages with a headless browser.


        For more information, see the [`renderJavaScript`
        documentation](https://www.algolia.com/doc/tools/crawler/apis/configuration/render-java-script/).
      oneOf:
        - type: boolean
          description: Whether to render all pages.
        - type: array
          description: URLs or URL patterns to render.
          items:
            type: string
            description: URL or URL pattern to render.
            example: https://www.example.com
        - title: headlessBrowserConfig
          type: object
          description: Configuration for rendering HTML.
          properties:
            enabled:
              type: boolean
              description: Whether to render matching URLs.
            patterns:
              type: array
              description: URLs or URL patterns to render.
              items:
                type: string
            adBlock:
              type: boolean
              description: >
                Whether to turn on the built-in adblocker.

                This blocks most ads and tracking scripts but can break some
                sites.
            waitTime:
              $ref: '#/components/schemas/waitTime'
          required:
            - enabled
            - patterns
    requestOptions:
      type: object
      description: Options to add to all HTTP requests made by the crawler.
      properties:
        proxy:
          type: string
          description: Proxy for all crawler requests.
        timeout:
          type: number
          default: 30000
          description: Timeout in milliseconds for the crawl.
        retries:
          type: number
          default: 3
          description: Maximum number of retries to crawl one URL.
        headers:
          $ref: '#/components/schemas/headers'
    beforeIndexPublishing:
      type: object
      description: >-
        Checks triggered after the crawl finishes but before the records are
        added to the Algolia index.
      properties:
        maxLostRecordsPercentage:
          type: number
          description: >-
            Maximum difference in percent between the numbers of records between
            crawls.
          minimum: 1
          maximum: 100
          default: 10
        maxFailedUrls:
          type: number
          description: Stops the crawler if a specified number of pages fail to crawl.
    safetyChecks:
      type: object
      description: >
        Checks to ensure the crawl was successful.


        For more information, see the [Safety
        checks](https://www.algolia.com/doc/tools/crawler/getting-started/crawler-configuration/#safety-checks)
        documentation.
      properties:
        beforeIndexPublishing:
          $ref: '#/components/schemas/beforeIndexPublishing'
    schedule:
      type: string
      description: >
        Schedule for running the crawl.


        For more information, see the [`schedule`
        documentation](https://www.algolia.com/doc/tools/crawler/apis/configuration/schedule/).
      example: every weekday at 12:00 pm
    Configuration:
      type: object
      description: Crawler configuration.
      required:
        - appId
        - rateLimit
        - actions
      properties:
        actions:
          type: array
          description: A list of actions.
          minItems: 1
          maxItems: 30
          items:
            $ref: '#/components/schemas/Action'
        apiKey:
          type: string
          description: >
            Algolia API key for indexing the records.


            For more information, see the [`apiKey`
            documentation](https://www.algolia.com/doc/tools/crawler/apis/configuration/api-key/).
        appId:
          $ref: '#/components/schemas/applicationID'
        exclusionPatterns:
          type: array
          description: URLs to exclude from crawling.
          maxItems: 100
          example:
            - https://www.example.com/excluded
            - '!https://www.example.com/this-one-url'
            - https://www.example.com/exclude/**
          items:
            type: string
            description: >
              URLs to exclude from crawling.


              Uses [micromatch](https://github.com/micromatch/micromatch) for
              negation, wildcards, and more.
        externalData:
          type: array
          description: >
            References to external data sources for enriching the extracted
            records.


            For more information, see [Enrich extracted records with external
            data](https://www.algolia.com/doc/tools/crawler/guides/enriching-extraction-with-external-data/).
          maxItems: 10
          items:
            type: string
            description: >-
              Reference to an external data source you configured in the Crawler
              dashboard.
            example: testCSV
        extraUrls:
          type: array
          maxItems: 9999
          description: >
            URLs from where to start crawling.


            For more information, see the [`extraUrls`
            documentation](https://www.algolia.com/doc/tools/crawler/apis/configuration/extra-urls/).
          items:
            type: string
        ignoreCanonicalTo:
          $ref: '#/components/schemas/ignoreCanonicalTo'
        ignoreNoFollowTo:
          type: boolean
          description: >
            Whether to ignore the `nofollow` meta tag or link attribute.


            For more information, see the [`ignoreNoFollowTo`
            documentation](https://www.algolia.com/doc/tools/crawler/apis/configuration/ignore-no-follow-to/).
        ignoreNoIndex:
          type: boolean
          description: |
            Whether to ignore the `noindex` robots meta tag.
            If `true` pages with this meta tag _will_ be crawled.
        ignoreQueryParams:
          type: array
          description: >
            Query parameters to ignore while crawling.


            All URLs with the matching query parameters will be treated as
            identical.

            This prevents indexing URLs that just differ by their query
            parameters.


            You can use wildcard characters to pattern match.
          maxItems: 9999
          example:
            - ref
            - utm_*
          items:
            type: string
            description: >-
              Query parameter to ignore. You can include wildcards to match a
              range of similar query parameters.
        ignoreRobotsTxtRules:
          type: boolean
          description: Whether to ignore rules defined in your `robots.txt` file.
        indexPrefix:
          type: string
          description: >-
            A prefix for all indices created by this crawler. It's combined with
            the `indexName` for each action to form the complete index name.
          maxLength: 64
          example: crawler_
        initialIndexSettings:
          type: object
          description: >
            Crawler index settings.


            For more information, see the [`initialIndexSettings`
            documentation](https://www.algolia.com/doc/tools/crawler/apis/configuration/initial-index-settings/).
          additionalProperties:
            $ref: '#/components/schemas/indexSettings'
            x-additionalPropertiesName: indexName
        linkExtractor:
          title: linkExtractor
          type: object
          description: >
            Function for extracting URLs from links on crawled pages.


            For more information, see the [`linkExtractor`
            documentation](https://www.algolia.com/doc/tools/crawler/apis/configuration/link-extractor/).
          properties:
            __type:
              $ref: '#/components/schemas/configurationRecordExtractorType'
            source:
              type: string
              example: |
                ({ $, url, defaultExtractor }) => {
                  if (/example.com\/doc\//.test(url.href)) {
                    // For all pages under `/doc`, only extract the first found URL.
                    return defaultExtractor().slice(0, 1)
                  }
                  // For all other pages, use the default.
                  return defaultExtractor()
                }
        login:
          $ref: '#/components/schemas/login'
        maxDepth:
          type: number
          description: >
            Maximum path depth of crawled URLs.

            For example, if `maxDepth` is 2, `https://example.com/foo/bar` is
            crawled,

            but `https://example.com/foo/bar/baz` won't.

            Trailing slashes increase the URL depth.
          minimum: 1
          maximum: 100
        maxUrls:
          type: number
          description: |
            Maximum number of crawled URLs.

            Setting `maxUrls` doesn't guarantee consistency between crawls
            because the crawler processes URLs in parallel.
          minimum: 1
          maximum: 15000000
        rateLimit:
          type: number
          description: >
            Number of concurrent tasks per second.


            If processing each URL takes _n_ seconds,

            your crawler can process `rateLimit / n` URLs per second.


            Higher numbers mean faster crawls but they also increase your
            bandwidth and server load.
          minimum: 1
          maximum: 100
          example: 4
        renderJavaScript:
          $ref: '#/components/schemas/renderJavaScript'
        requestOptions:
          $ref: '#/components/schemas/requestOptions'
        safetyChecks:
          $ref: '#/components/schemas/safetyChecks'
        saveBackup:
          type: boolean
          description: >
            Whether to back up your index before the crawler overwrites it with
            new records.
        schedule:
          $ref: '#/components/schemas/schedule'
        sitemaps:
          type: array
          description: Sitemaps with URLs from where to start crawling.
          maxItems: 9999
          items:
            type: string
            example: https://example.com/sitemap.xyz
        startUrls:
          type: array
          description: URLs from where to start crawling.
          maxItems: 9999
          items:
            type: string
            example: https://www.example.com
    createdAt:
      type: string
      example: '2023-07-04T12:49:15Z'
      description: Date and time when the object was created, in RFC 3339 format.
    updatedAt:
      type: string
      example: '2023-07-04T12:49:15Z'
      description: Date and time when the object was updated, in RFC 3339 format.
    BaseResponse:
      title: Without configuration
      type: object
      properties:
        name:
          $ref: '#/components/schemas/CrawlerName'
        createdAt:
          $ref: '#/components/schemas/createdAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
        running:
          type: boolean
          description: Whether this crawler is active.
        reindexing:
          type: boolean
          description: Whether this crawler is completely reindexing your content.
        blocked:
          type: boolean
          description: >
            Whether this crawler is currently blocked.


            If `true`, you can unblock it from the [Crawler
            page](https://dashboard.algolia.com/crawler) in the Algolia
            dashboard

            or by [cancelling the blocking
            task](#tag/tasks/operation/cancelBlockingAction).
        blockingError:
          type: string
          description: Reason why the crawler is blocked.
          example: |
            Error: Failed to fetch external data for source 'testCSV': 404
        blockingTaskId:
          type: string
          description: ID of the task that's blocking the crawler.
        lastReindexStartAt:
          default: null
          oneOf:
            - type: string
              description: Date and time when the last crawl started, in RFC 3339 format.
              example: '2024-04-07T09:16:04Z'
            - type: 'null'
        lastReindexEndedAt:
          default: null
          oneOf:
            - type: string
              description: Date and time when the last crawl finished, in RFC 3339 format.
            - type: 'null'
      required:
        - name
        - createdAt
        - updatedAt
        - running
        - reindexing
        - blocked
        - lastReindexStartAt
        - lastReindexEndedAt
    WithConfiguration:
      title: With configuration
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            config:
              $ref: '#/components/schemas/Configuration'
      required:
        - name
        - createdAt
        - updatedAt
        - running
        - reindexing
        - blocked
        - lastReindexStartAt
        - lastReindexEndedAt
        - config
    GetCrawlerResponse:
      title: API response for retrieving crawler information
      oneOf:
        - $ref: '#/components/schemas/BaseResponse'
        - $ref: '#/components/schemas/WithConfiguration'
    TaskID:
      type: string
      description: Universally unique identifier (UUID) of the task.
      example: 98458796-b7bb-4703-8b1b-785c1080b110
    PartialConfig:
      description: |
        Crawler configuration to update.
        You can only update top-level configuration properties.
        To update a nested configuration, such as `actions.recordExtractor`,
        you must provide the complete top-level object such as `actions`.
      allOf:
        - $ref: '#/components/schemas/Configuration'
    urlsCrawledGroupStatus:
      type: string
      description: >
        Crawled URL status.


        For more information, see [Troubleshooting by crawl
        status](https://www.algolia.com/doc/tools/crawler/troubleshooting/crawl-status/).
      enum:
        - DONE
        - SKIPPED
        - FAILED
    urlsCrawledGroupCategory:
      type: string
      description: >
        Step where the status information was generated.


        For more information, see [Troubleshooting by crawl
        status](https://www.algolia.com/doc/tools/crawler/troubleshooting/crawl-status/).
      enum:
        - fetch
        - extraction
        - indexing
        - success
    UrlsCrawledGroup:
      type: object
      description: Processed URLs and their status.
      properties:
        status:
          $ref: '#/components/schemas/urlsCrawledGroupStatus'
        reason:
          type: string
          description: Reason for this status.
        category:
          $ref: '#/components/schemas/urlsCrawledGroupCategory'
        count:
          type: integer
          description: Number of URLs with this status.
        readable:
          type: string
          description: Reason for this status.
      example:
        status: SKIPPED
        reason: forbidden_by_robotstxt
        category: fetch
        count: 3
        readable: Forbidden by robots.txt
    version:
      type: integer
      description: >-
        Version of the configuration. Version 1 is the initial configuration you
        used when creating the crawler.
      minimum: 1
    authorId:
      type: string
      description: >-
        Universally unique identifier (UUID) of the user who created this
        version of the configuration.
      example: 7d79f0dd-2dab-4296-8098-957a1fdc0637
    crawlerConfigVersionsResponse:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            items:
              type: array
              description: Configuration changes.
              items:
                title: crawlerConfigVersionsResponse
                type: object
                properties:
                  version:
                    $ref: '#/components/schemas/version'
                  createdAt:
                    $ref: '#/components/schemas/createdAt'
                  authorId:
                    $ref: '#/components/schemas/authorId'
                required:
                  - version
                  - createdAt
                  - authorId
    domainsResponse:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            items:
              type: array
              items:
                title: domainResponse
                type: object
                properties:
                  appId:
                    $ref: '#/components/schemas/applicationID'
                  domain:
                    type: string
                    description: Domain name which crawlers can access.
                    example: wwww.algolia.com
                  validated:
                    type: boolean
                    description: Whether the domain is validated.
  parameters:
    ItemsPerPage:
      name: itemsPerPage
      in: query
      description: Number of items per page to retrieve.
      schema:
        $ref: '#/components/schemas/itemsPerPage'
    Page:
      name: page
      in: query
      description: Page to retrieve.
      schema:
        $ref: '#/components/schemas/page'
    Name:
      name: name
      in: query
      description: Name of the crawler for filtering the API response.
      schema:
        $ref: '#/components/schemas/CrawlerName'
    AppID:
      name: appID
      in: query
      description: Algolia application ID for filtering the API response.
      schema:
        $ref: '#/components/schemas/applicationID'
    CrawlerIdParameter:
      name: id
      in: path
      description: Crawler ID.
      required: true
      schema:
        $ref: '#/components/schemas/CrawlerID'
    CrawlerVersionParameter:
      name: version
      in: path
      description: This crawler's version nmber.
      required: true
      schema:
        type: integer
    TaskIdParameter:
      name: taskID
      in: path
      description: Task ID.
      required: true
      schema:
        $ref: '#/components/schemas/TaskID'
  responses:
    InvalidRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            title: invalidRequest
            type: object
            properties:
              error:
                title: invalidRequestError
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      title: errorItem
                      type: object
                      properties:
                        code:
                          type: string
                        message:
                          type: string
                        line:
                          type: integer
                        position:
                          type: integer
                      required:
                        - message
                      example:
                        message: url is not defined
                        line: 5
                example:
                  code: malformed_id
            required:
              - error
    MissingAuthorization:
      description: Authorization information is missing or invalid.
    NoRightsOnCrawler:
      description: >-
        The user doesn't have enough rights on the specified Crawler, or it
        doesn't exists.
    ActionAcknowledged:
      description: OK
      content:
        application/json:
          schema:
            title: actionAcknowledged
            type: object
            properties:
              taskId:
                $ref: '#/components/schemas/TaskID'
            required:
              - taskId
    Forbidden:
      description: Invalid credentials.
      content:
        application/json:
          schema:
            title: forbidden
            type: object
            properties:
              error:
                title: forbiddenError
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      title: errorItem
                      type: object
                      properties:
                        code:
                          type: string
                        message:
                          type: string
                        line:
                          type: integer
                        position:
                          type: integer
                      required:
                        - message
                      example:
                        message: url is not defined
                        line: 5
                example:
                  code: malformed_id
            required:
              - error
