---
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/4371/api/doc/elasticsearch/v8/operation/operation-synonyms-put-synonym
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-synonyms-put-synonym
products:
  - Elasticsearch
---

# Create or update a synonym set

Availability: 8.10+

## Paths

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

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#bearerauth)

#### Path Parameters

- `id` (string Id)
  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.
  `SynonymRule` or `SynonymRule[]`
  - `id` (string Id) — 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.

## Response

`application/json`

- `result` (enum Result)
  Values: `created`, `updated`, `deleted`, `not_found`, `noop`
- `reload_analyzers_details` ({} ReloadResult)
  - `reload_details` ([] ReloadDetails)
    - `index` (string)
    - `reloaded_analyzers` ([] string)
    - `reloaded_node_ids` ([] string)
  - `_shards` ({} ShardStatistics)
    - `failed` (number uint)
      The number of shards the operation or search attempted to run on but failed.
    - `successful` (number uint)
      The number of shards the operation or search succeeded on.
    - `total` (number uint)
      The number of shards the operation or search will run on overall.
    - `failures` ([] ShardFailure)
      - `index` (string IndexName)
      - `node` (string)
      - `reason` ({} ErrorCause)
        - `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` ({} ErrorCause) — recursive
          Same fields as `reason` in `failures`
        - `root_cause` ([] ErrorCause) — recursive
          Same fields as `reason` in `failures`
        - `suppressed` ([] ErrorCause) — recursive
          Same fields as `reason` in `failures`
      - `shard` (number)
      - `status` (string)
      - `primary` (boolean)
    - `skipped` (number uint)
## 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"
)
```