openapi: 3.2.0
info:
  title: Elasticsearch Request & Response Specification Synonyms API
  license:
    name: Apache 2.0
    url: https://github.com/elastic/elasticsearch-specification/blob/main/LICENSE
  version: ''
tags:
- name: synonyms
paths:
  /_synonyms/{id}:
    get:
      tags:
      - synonyms
      summary: Get a synonym set
      description: '


        ## Required authorization


        * Cluster privileges: `manage_search_synonyms`

        '
      operationId: synonyms-get-synonym
      parameters:
      - in: path
        name: id
        description: The synonyms set identifier to retrieve.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      - in: query
        name: from
        description: The starting offset for synonym rules to retrieve.
        deprecated: false
        schema:
          default: 0.0
          type: number
        style: form
      - in: query
        name: size
        description: The max number of synonym rules to retrieve.
        deprecated: false
        schema:
          default: 10.0
          type: number
        style: form
      - in: query
        name: search_after
        description: 'The synonym rule ID to use as a cursor for pagination.

          The next page of results will start after this rule ID.

          This parameter cannot be used with `from`.'
        deprecated: false
        schema:
          type: string
        x-state: Generally available; Added in 9.5.0
        style: form
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    description: The total number of synonyms rules that the synonyms set contains.
                    type: number
                  synonyms_set:
                    description: Synonym rule details.
                    type: array
                    items:
                      $ref: '#/components/schemas/synonyms._types.SynonymRuleRead'
                required:
                - count
                - synonyms_set
              examples:
                SynonymsGetResponseExample1:
                  description: A successful response from `GET _synonyms/my-synonyms-set`.
                  value: "{\n  \"count\": 3,\n  \"synonyms_set\": [\n    {\n      \"id\": \"test-1\",\n      \"synonyms\": \"hello, hi\"\n    },\n    {\n      \"id\": \"test-2\",\n      \"synonyms\": \"bye, goodbye\"\n    },\n    {\n      \"id\": \"test-3\",\n      \"synonyms\": \"test => check\"\n    }\n  ]\n}"
      x-state: Generally available; Added in 8.10.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
    put:
      tags:
      - synonyms
      summary: Create or update a synonym set
      description: 'Synonym sets are limited to a maximum of 100,000 synonym rules per set by default.

        This limit is configurable using the `synonyms.max_synonym_rules` cluster setting.


        When an existing synonyms set is updated, the search analyzers that use the synonyms set are reloaded automatically for all indices.

        This is equivalent to invoking the reload search analyzers API for all indices that use the synonyms set.


        For practical examples of how to create or update a synonyms set, refer to the External documentation.


        ## Required authorization


        * Cluster privileges: `manage_search_synonyms`

        '
      externalDocs:
        description: About synonym API examples
        url: https://www.elastic.co/docs/solutions/search/full-text/create-update-synonyms-api-example
        x-previousVersionUrl: https://www.elastic.co/guide/en/elasticsearch/reference/8.19/put-synonyms-set.html
      operationId: synonyms-put-synonym
      parameters:
      - in: path
        name: id
        description: The ID of the synonyms set to be created or updated.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      - in: query
        name: refresh
        description: 'If `true`, the request will refresh the analyzers with the new synonyms set and wait for the new synonyms to be available before returning.

          If `false`, analyzers will not be reloaded with the new synonym set'
        deprecated: false
        schema:
          default: true
          type: boolean
        x-state: Generally available; Added in 9.1.0
        style: form
      - in: query
        name: append
        description: 'If `true`, the provided synonym rules are appended to the existing set, with matching IDs overwriting existing rules.

          If `false`, the entire synonyms set is replaced with the new synonym rules definitions.'
        deprecated: false
        schema:
          default: false
          type: boolean
        x-state: Generally available; Added in 9.5.0
        style: form
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                synonyms_set:
                  description: The synonym rules definitions for the synonyms set.
                  oneOf:
                  - $ref: '#/components/schemas/synonyms._types.SynonymRule'
                  - type: array
                    items:
                      $ref: '#/components/schemas/synonyms._types.SynonymRule'
              required:
              - synonyms_set
            examples:
              SynonymsPutRequestExample1:
                description: ''
                value: "\n{\n  \"synonyms_set\": {\n  \"synonyms\" : \"hello, hi, howdy\"\n  }\n}"
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    description: The update operation result.
                    allOf:
                    - $ref: '#/components/schemas/_types.Result'
                  reload_analyzers_details:
                    description: 'Updating a synonyms set can reload the associated analyzers in case refresh is set to true.

                      This information is the analyzers reloading result.'
                    allOf:
                    - $ref: '#/components/schemas/indices.reload_search_analyzers.ReloadResult'
                required:
                - result
      x-state: Generally available; Added in 8.10.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
    delete:
      tags:
      - synonyms
      summary: Delete a synonym set
      description: 'You can only delete a synonyms set that is not in use by any index analyzer.


        Synonyms sets can be used in synonym graph token filters and synonym token filters.

        These synonym filters can be used as part of search analyzers.


        Analyzers need to be loaded when an index is restored (such as when a node starts, or the index becomes open).

        Even if the analyzer is not used on any field mapping, it still needs to be loaded on the index recovery phase.


        If any analyzers cannot be loaded, the index becomes unavailable and the cluster status becomes red or yellow as index shards are not available.

        To prevent that, synonyms sets that are used in analyzers can''t be deleted.

        A delete request in this case will return a 400 response code.


        To remove a synonyms set, you must first remove all indices that contain analyzers using it.

        You can migrate an index by creating a new index that does not contain the token filter with the synonyms set, and use the reindex API in order to copy over the index data.

        Once finished, you can delete the index.

        When the synonyms set is not used in analyzers, you will be able to delete it.


        ## Required authorization


        * Cluster privileges: `manage_search_synonyms`

        '
      operationId: synonyms-delete-synonym
      parameters:
      - in: path
        name: id
        description: The synonyms set identifier to delete.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_types.AcknowledgedResponseBase'
      x-state: Generally available; Added in 8.10.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_synonyms/{set_id}/{rule_id}:
    get:
      tags:
      - synonyms
      summary: Get a synonym rule
      description: 'Get a synonym rule from a synonym set.


        ## Required authorization


        * Cluster privileges: `manage_search_synonyms`

        '
      operationId: synonyms-get-synonym-rule
      parameters:
      - in: path
        name: set_id
        description: The ID of the synonym set to retrieve the synonym rule from.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      - in: path
        name: rule_id
        description: The ID of the synonym rule to retrieve.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/synonyms._types.SynonymRuleRead'
              examples:
                SynonymRuleGetResponseExample1:
                  description: A successful response from `GET _synonyms/my-synonyms-set/test-1`.
                  value: "{\n  \"id\": \"test-1\",\n  \"synonyms\": \"hello, hi\"\n}"
      x-state: Generally available; Added in 8.10.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
    put:
      tags:
      - synonyms
      summary: Create or update a synonym rule
      description: 'Create or update a synonym rule in a synonym set.


        If any of the synonym rules included is invalid, the API returns an error.


        When you update a synonym rule, all analyzers using the synonyms set will be reloaded automatically to reflect the new rule.


        ## Required authorization


        * Cluster privileges: `manage_search_synonyms`

        '
      operationId: synonyms-put-synonym-rule
      parameters:
      - in: path
        name: set_id
        description: The ID of the synonym set.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      - in: path
        name: rule_id
        description: The ID of the synonym rule to be updated or created.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      - in: query
        name: refresh
        description: 'If `true`, the request will refresh the analyzers with the new synonym rule and wait for the new synonyms to be available before returning.

          If `false`, analyzers will not be reloaded with the new synonym rule'
        deprecated: false
        schema:
          default: true
          type: boolean
        x-state: Generally available; Added in 9.1.0
        style: form
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                synonyms:
                  externalDocs:
                    url: https://www.elastic.co/docs/reference/text-analysis/analysis-synonym-graph-tokenfilter#analysis-synonym-graph-define-synonyms
                  description: The synonym rule information definition, which must be in Solr format.
                  allOf:
                  - $ref: '#/components/schemas/synonyms._types.SynonymString'
              required:
              - synonyms
            examples:
              SynonymRulePutRequestExample1:
                summary: synonyms/apis/put-synonym-rule.asciidoc:107
                description: ''
                value: "{\n  \"synonyms\": \"hello, hi, howdy\"\n}"
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/synonyms._types.SynonymsUpdateResult'
              examples:
                SynonymRuleResponseExample1:
                  description: 'A successful response from `PUT _synonyms/my-synonyms-set/test-1`.

                    '
                  value: "{\n  \"result\": \"updated\",\n  \"reload_analyzers_details\": {\n    \"_shards\": {\n      \"total\": 2,\n      \"successful\": 1,\n      \"failed\": 0\n    },\n    \"reload_details\": [\n      {\n        \"index\": \"test-index\",\n        \"reloaded_analyzers\": [\n          \"my_search_analyzer\"\n        ],\n        \"reloaded_node_ids\": [\n          \"1wYFZzq8Sxeu_Jvt9mlbkg\"\n        ]\n      }\n    ]\n  }\n}"
      x-state: Generally available; Added in 8.10.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
    delete:
      tags:
      - synonyms
      summary: Delete a synonym rule
      description: 'Delete a synonym rule from a synonym set.


        ## Required authorization


        * Cluster privileges: `manage_search_synonyms`

        '
      operationId: synonyms-delete-synonym-rule
      parameters:
      - in: path
        name: set_id
        description: The ID of the synonym set to update.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      - in: path
        name: rule_id
        description: The ID of the synonym rule to delete.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      - in: query
        name: refresh
        description: 'If `true`, the request will refresh the analyzers with the deleted synonym rule and wait for the new synonyms to be available before returning.

          If `false`, analyzers will not be reloaded with the deleted synonym rule'
        deprecated: false
        schema:
          default: true
          type: boolean
        x-state: Generally available; Added in 9.1.0
        style: form
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/synonyms._types.SynonymsUpdateResult'
              examples:
                SynonymRuleDeleteResponseExample1:
                  description: 'A successful response from `DELETE _synonyms/my-synonyms-set/test-1`. All analyzers using this synonyms set will be reloaded automatically to reflect the rule being deleted.

                    '
                  value: "{\n  \"result\": \"deleted\",\n  \"reload_analyzers_details\": {\n    \"_shards\": {\n      \"total\": 2,\n      \"successful\": 1,\n      \"failed\": 0\n    },\n    \"reload_details\": [\n      {\n        \"index\": \"test-index\",\n        \"reloaded_analyzers\": [\n          \"my_search_analyzer\"\n        ],\n        \"reloaded_node_ids\": [\n          \"1wYFZzq8Sxeu_Jvt9mlbkg\"\n        ]\n      }\n    ]\n  }\n}"
      x-state: Generally available; Added in 8.10.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_synonyms:
    get:
      tags:
      - synonyms
      summary: Get all synonym sets
      description: 'Get a summary of all defined synonym sets.


        ## Required authorization


        * Cluster privileges: `manage_search_synonyms`

        '
      operationId: synonyms-get-synonyms-sets
      parameters:
      - in: query
        name: from
        description: The starting offset for synonyms sets to retrieve.
        deprecated: false
        schema:
          default: 0.0
          type: number
        style: form
      - in: query
        name: size
        description: The maximum number of synonyms sets to retrieve.
        deprecated: false
        schema:
          default: 10.0
          type: number
        style: form
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    description: The total number of synonyms sets defined.
                    type: number
                  results:
                    description: The identifier and total number of defined synonym rules for each synonyms set.
                    type: array
                    items:
                      $ref: '#/components/schemas/synonyms.get_synonyms_sets.SynonymsSetItem'
                required:
                - count
                - results
              examples:
                SynonymsSetsGetResponseExample1:
                  description: A successful response from `GET _synonyms`.
                  value: "{\n  \"count\": 3,\n  \"results\": [\n    {\n      \"synonyms_set\": \"ecommerce-synonyms\",\n      \"count\": 2\n    },\n    {\n      \"synonyms_set\": \"my-synonyms-set\",\n      \"count\": 3\n    },\n    {\n      \"synonyms_set\": \"new-ecommerce-synonyms\",\n      \"count\": 1\n    }\n  ]\n}"
      x-state: Generally available; Added in 8.10.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
components:
  schemas:
    _types.ShardStatistics:
      type: object
      properties:
        failed:
          description: The number of shards the operation or search attempted to run on but failed.
          allOf:
          - $ref: '#/components/schemas/_types.uint'
        successful:
          description: The number of shards the operation or search succeeded on.
          allOf:
          - $ref: '#/components/schemas/_types.uint'
        total:
          description: The number of shards the operation or search will run on overall.
          allOf:
          - $ref: '#/components/schemas/_types.uint'
        failures:
          type: array
          items:
            $ref: '#/components/schemas/_types.ShardFailure'
        skipped:
          allOf:
          - $ref: '#/components/schemas/_types.uint'
      required:
      - failed
      - successful
      - total
    _types.Result:
      type: string
      enum:
      - created
      - updated
      - deleted
      - not_found
      - noop
    synonyms._types.SynonymRule:
      type: object
      properties:
        id:
          description: 'The identifier for the synonym rule.

            If you do not specify a synonym rule ID when you create a rule, an identifier is created automatically by Elasticsearch.'
          allOf:
          - $ref: '#/components/schemas/_types.Id'
        synonyms:
          externalDocs:
            url: https://www.elastic.co/docs/reference/text-analysis/analysis-synonym-graph-tokenfilter#analysis-synonym-graph-define-synonyms
          description: The synonyms that conform the synonym rule in Solr format.
          allOf:
          - $ref: '#/components/schemas/synonyms._types.SynonymString'
      required:
      - synonyms
    _types.ErrorCause:
      description: 'Cause and details about a request failure. This class defines the properties common to all error types.

        Additional details are also provided, that depend on the error type.'
      type: object
      properties:
        type:
          description: The type of error
          type: string
        reason:
          description: A human-readable explanation of the error, in English.
          oneOf:
          - type: string
          - type:
            - string
            - 'null'
        stack_trace:
          description: The server stack trace. Present only if the `error_trace=true` parameter was sent with the request.
          type: string
        caused_by:
          allOf:
          - $ref: '#/components/schemas/_types.ErrorCause'
        root_cause:
          type: array
          items:
            $ref: '#/components/schemas/_types.ErrorCause'
        suppressed:
          type: array
          items:
            $ref: '#/components/schemas/_types.ErrorCause'
      required:
      - type
    _types.IndexName:
      type: string
    synonyms.get_synonyms_sets.SynonymsSetItem:
      type: object
      properties:
        synonyms_set:
          description: Synonyms set identifier
          allOf:
          - $ref: '#/components/schemas/_types.Id'
        count:
          description: Number of synonym rules that the synonym set contains
          type: number
      required:
      - synonyms_set
      - count
    _types.Id:
      type: string
    _types.uint:
      type: number
    _types.AcknowledgedResponseBase:
      type: object
      properties:
        acknowledged:
          description: For a successful response, this value is always true. On failure, an exception is returned instead.
          type: boolean
      required:
      - acknowledged
    synonyms._types.SynonymString:
      type: string
    synonyms._types.SynonymsUpdateResult:
      type: object
      properties:
        result:
          description: The update operation result.
          allOf:
          - $ref: '#/components/schemas/_types.Result'
        reload_analyzers_details:
          description: 'Updating synonyms in a synonym set can reload the associated analyzers in case refresh is set to true.

            This information is the analyzers reloading result.'
          allOf:
          - $ref: '#/components/schemas/indices.reload_search_analyzers.ReloadResult'
      required:
      - result
    _types.ShardFailure:
      type: object
      properties:
        index:
          allOf:
          - $ref: '#/components/schemas/_types.IndexName'
        node:
          type: string
        reason:
          allOf:
          - $ref: '#/components/schemas/_types.ErrorCause'
        shard:
          type: number
        status:
          type: string
        primary:
          type: boolean
      required:
      - reason
    indices.reload_search_analyzers.ReloadDetails:
      type: object
      properties:
        index:
          type: string
        reloaded_analyzers:
          type: array
          items:
            type: string
        reloaded_node_ids:
          type: array
          items:
            type: string
      required:
      - index
      - reloaded_analyzers
      - reloaded_node_ids
    indices.reload_search_analyzers.ReloadResult:
      type: object
      properties:
        reload_details:
          type: array
          items:
            $ref: '#/components/schemas/indices.reload_search_analyzers.ReloadDetails'
        _shards:
          allOf:
          - $ref: '#/components/schemas/_types.ShardStatistics'
      required:
      - reload_details
      - _shards
    synonyms._types.SynonymRuleRead:
      type: object
      properties:
        id:
          description: 'The identifier for the synonym rule.

            If you do not specify a synonym rule ID when you create a rule, an identifier is created automatically by Elasticsearch.'
          allOf:
          - $ref: '#/components/schemas/_types.Id'
        synonyms:
          externalDocs:
            url: https://www.elastic.co/docs/reference/text-analysis/analysis-synonym-graph-tokenfilter#analysis-synonym-graph-define-synonyms
          description: The synonyms that conform the synonym rule in Solr format.
          allOf:
          - $ref: '#/components/schemas/synonyms._types.SynonymString'
      required:
      - id
      - synonyms