---
type: api
title: Create or update a synonym set
description: Synonyms sets are limited to a maximum of 10,000 synonym rules per set.
url: https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/v8/operation/operation-synonyms-put-synonym
resource: https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/v8/operation/operation-synonyms-put-synonym
products:
  - Elasticsearch
---

# Create or update a synonym set

Authentication: required

Availability: Generally available since 8.10

## Paths

- `PUT` `/_synonyms/{id}`

#### Path parameters

- `id` (string) — required
  The ID of the synonyms set to be created or updated.

## Description

Synonyms sets are limited to a maximum of 10,000 synonym rules per set.
If you need to manage more synonym rules, you can create multiple synonym sets.

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.

## Required authorization

- Cluster privileges: `manage_search_synonyms`

## Request body

`application/json`

- `synonyms_set` (union oneOf) — required
  The synonym rules definitions for the synonyms set.
  `object` or `object[]`
  - `id` (string) — optional
    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.
  - `synonyms` (string) — required
    The synonyms that conform the synonym rule in Solr format.

## Responses

#### `200`

`application/json`

- `result` (enum)
  Values: `created`, `updated`, `deleted`, `not_found`, `noop`
- `reload_analyzers_details` (object)
  - `reload_details` (object[])
    - `index` (string)
    - `reloaded_analyzers` (string[])
    - `reloaded_node_ids` (string[])
  - `_shards` (object)
    - `failed` (number)
      The number of shards the operation or search attempted to run on but failed.
    - `successful` (number)
      The number of shards the operation or search succeeded on.
    - `total` (number)
      The number of shards the operation or search will run on overall.
    - `failures` (object[])
      - `index` (string)
      - `node` (string)
      - `reason` (object)
        - `type` (string)
          The type of error
        - `reason` (union string) — nullable
          A human-readable explanation of the error, in English.
          One of: `string`
        - `stack_trace` (string)
          The server stack trace. Present only if the `error_trace=true` parameter was sent with the request.
        - `caused_by` (object) — recursive
          Same fields as `reason` in `failures`
        - `root_cause` (object[]) — recursive
          Same fields as `reason` in `failures`
        - `suppressed` (object[]) — recursive
          Same fields as `reason` in `failures`
      - `shard` (number)
      - `status` (string)
      - `primary` (boolean)
    - `skipped` (number)
#### `400`


The synonym rules are not valid.

`application/json`

- `error` (object)
  - `type` (string)
    The type of error
  - `reason` (union string) — nullable
    A human-readable explanation of the error, in English.
    One of: `string`
  - `stack_trace` (string)
    The server stack trace. Present only if the `error_trace=true` parameter was sent with the request.
  - `caused_by` (object) — recursive
    Same fields as `error`
  - `root_cause` (object[]) — recursive
    Same fields as `error`
  - `suppressed` (object[]) — recursive
    Same fields as `error`
- `status` (number)
## Code examples

#### Console

```console
PUT _synonyms/my-synonyms-set
```

#### JavaScript

```javascript
const response = await client.synonyms.putSynonym({
  id: "my-synonyms-set",
});
```

#### Python

```python
resp = client.synonyms.put_synonym(
    id="my-synonyms-set",
)
```

#### curl

```curl
curl -X PUT "$ELASTICSEARCH_URL/_synonyms/my-synonyms-set" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY"
```

#### PHP

```php
$resp = $client->synonyms()->putSynonym([
    "id" => "my-synonyms-set",
]);
```

#### Ruby

```ruby
response = client.synonyms.put_synonym(
  id: "my-synonyms-set"
)
```

## Response examples

#### 200

`application/json`

Generated from the API spec. Values are representative. Unions use the first variant; deeply nested or large bodies may omit fields.

```json
{
  "result": "created",
  "reload_analyzers_details": {
    "reload_details": [
      {
        "index": "string",
        "reloaded_analyzers": [
          "string"
        ],
        "reloaded_node_ids": [
          "string"
        ]
      }
    ],
    "_shards": {
      "failed": 0,
      "successful": 0,
      "total": 0,
      "failures": [
        {
          "index": "string",
          "node": "string",
          "reason": {
            "type": "string",
            "stack_trace": "string"
          },
          "shard": 0,
          "status": "string",
          "primary": false
        }
      ],
      "skipped": 0
    }
  }
}
```

#### Synonyms put response example1

`application/json`

An abbreviated response from `PUT _synonyms/my-synonyms-set`. If any of the synonym rules included is not valid, the API returns an error.

```json
{
  "error": {
    "root_cause": [
      {
        "type": "action_request_validation_exception",
        "reason": "Validation Failed: 1: More than one explicit mapping specified in the same synonyms rule: [hello => hi => howdy];",
        "stack_trace": ...
      }
    ],
    "type": "action_request_validation_exception",
    "reason": "Validation Failed: 1: More than one explicit mapping specified in the same synonyms rule: [hello => hi => howdy];",
    "stack_trace": ...
  },
  "status": 400
}
```