> For a complete page index of the Captain API documentation, fetch https://docs.captain.dev/llms.txt?excludeSpec=true

# Replace Synonyms

PUT https://acme.captain.dev/v1/indexes/{index}/synonyms
Content-Type: application/json

Replace the index's synonyms. They apply to the next search, with no rebuild.

Reference: https://docs.captain.dev/reference/product-search/indexes/replace-synonyms

## Authentication

- `Authorization` header (bearer token, required) — A write key, issued by Captain. Server side only. Sent as Authorization: Bearer \<key>.

## Request

### Path parameters

- `index` (string, required) — index name

### Headers

- `Idempotency-Key` (string, optional) — Replays within 24 hours return the stored response (header Idempotent-Replayed: true). The same key on a different request answers 422. A concurrent duplicate answers 409. Failed requests do not keep the key.

### Body (application/json)

This endpoint expects an object.

- `synonyms` (list of Synonym, optional)

## Response

### 200

saved

## Types

### Synonym

- `objectID` (string, optional)
- `type` (enum, optional)
  - Allowed values: `synonym`, `oneWaySynonym`
- `synonyms` (list of string, optional)
- `input` (string, optional)

## Examples

**Request**

```json
{
  "synonyms": [
    {
      "objectID": "s1",
      "type": "synonym",
      "synonyms": [
        "sofa",
        "couch",
        "settee"
      ]
    },
    {
      "objectID": "s2",
      "type": "oneWaySynonym",
      "synonyms": [
        "television"
      ],
      "input": "tv"
    }
  ]
}
```

**Response**

```json
{
  "synonyms": [
    {
      "objectID": "s1",
      "type": "synonym",
      "synonyms": [
        "sofa",
        "couch",
        "settee"
      ]
    },
    {
      "objectID": "s2",
      "type": "oneWaySynonym",
      "input": "tv",
      "synonyms": [
        "television"
      ]
    }
  ]
}
```

**SDK Code**

```python Python REST
import json
import requests
import uuid

BASE_URL = "https://acme.captain.dev"
API_KEY = "your_write_key"
INDEX = "products"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "Idempotency-Key": str(uuid.uuid4()),
}

response = requests.put(
    f"{BASE_URL}/v1/indexes/{INDEX}/synonyms",
    headers=headers,
    json={
        "synonyms": [
            {
                "objectID": "s1",
                "type": "synonym",
                "synonyms": ["sofa", "couch", "settee"],
            },
            {
                "objectID": "s2",
                "type": "oneWaySynonym",
                "input": "tv",
                "synonyms": ["television"],
            },
        ],
    },
    timeout=30.0,
)

print(json.dumps(response.json(), indent=2))
```

```typescript TypeScript REST
const BASE_URL = "https://acme.captain.dev";
const API_KEY = "your_write_key";
const index = "products";

const response = await fetch(`${BASE_URL}/v1/indexes/${index}/synonyms`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    synonyms: [
      { objectID: "s1", type: "synonym", synonyms: ["sofa", "couch", "settee"] },
      { objectID: "s2", type: "oneWaySynonym", input: "tv", synonyms: ["television"] },
    ],
  }),
});

const result = await response.json();
console.log(JSON.stringify(result, null, 2));
```