Elastic Stack

Elastic Stack (ELK Stack) Synonyms API

The synonyms API from Elastic Stack (ELK Stack) — 3 operation(s) for synonyms.

GitHub OpenAPI

Operations 7

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /_synonyms/{id} Get the rules in a synonym set · Get a synonym set #
Ask an LLM
“What synonym rules are in a particular synonym set?”
“Can I page through a large synonym set?”
Tell an agent
Get synonym set {id}.
Show {size} rules from synonym set {id} starting at {from}.
PUT /_synonyms/{id} Create or replace a synonym set · Create or update a synonym set #
Ask an LLM
“How do I create a synonym set for my search analyzer?”
“Can I append rules to a synonym set instead of replacing it?”
Tell an agent
Create synonym set {id} with rules {synonyms_set}.
Add rules {synonyms_set} to synonym set {id} with append {append}.
DELETE /_synonyms/{id} Delete a synonym set · Delete a synonym set #
Ask an LLM
“How do I delete a synonym set?”
“Why can't I delete a synonym set that an analyzer is using?”
Tell an agent destructive · confirm first
Delete synonym set {id}.
Remove the unused synonym set {id}.
GET /_synonyms/{set_id}/{rule_id} Get a single synonym rule · Get a synonym rule #
Ask an LLM
“What does one specific rule in a synonym set say?”
“Can I fetch a synonym rule by its rule id?”
Tell an agent
Get rule {rule_id} from synonym set {set_id}.
Show synonym rule {rule_id} in {set_id}.
PUT /_synonyms/{set_id}/{rule_id} Create or update a single synonym rule · Create or update a synonym rule #
Ask an LLM
“How do I add or change one synonym rule without resending the whole set?”
“Do analyzers reload when I update a single synonym rule?”
Tell an agent
Set rule {rule_id} in synonym set {set_id} to {synonyms}.
Update synonym rule {rule_id} in {set_id} to {synonyms} with refresh {refresh}.
DELETE /_synonyms/{set_id}/{rule_id} Delete a single synonym rule · Delete a synonym rule #
Ask an LLM
“How do I remove one rule from a synonym set?”
“Can I delete a synonym rule and keep the rest of the set?”
Tell an agent destructive · confirm first
Delete rule {rule_id} from synonym set {set_id}.
Remove synonym rule {rule_id} in {set_id} with refresh {refresh}.
GET /_synonyms List all synonym sets · Get all synonym sets #
Ask an LLM
“Which synonym sets are defined in my cluster?”
“How many rules does each synonym set have?”
Tell an agent
List all synonym sets.
Show {size} synonym sets starting at {from}.

Documentation

📖
Documentation
https://www.elastic.co/docs/reference/elasticsearch
📖
APIReference
https://www.elastic.co/docs/api/doc/elasticsearch/
📖
Documentation
https://www.elastic.co/docs/reference/kibana
📖
APIReference
https://www.elastic.co/docs/api/doc/kibana/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/elk-stack/refs/heads/main/openapi/elk-stack-synonyms-api-openapi.yml

Other Resources

🔗
SourceCode
https://github.com/elastic/elasticsearch-specification
🔗
SourceCode
https://github.com/elastic/kibana
🔗
ToolCrosswalk
https://raw.githubusercontent.com/api-evangelist/elk-stack/refs/heads/main/mcp/elk-stack-tool-crosswalk.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/elk-stack:elk-stack-synonyms-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

elk-stack-synonyms-api-openapi.yml Raw ↑ 
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.Result:
      type: string
      enum:
      - created
      - updated
      - deleted
      - not_found
      - noop
    _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
    _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.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
    _types.uint:
      type: number
    synonyms._types.SynonymString:
      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
    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
    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
    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
    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
    _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.IndexName:
      type: string
    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