---
title: Using the Synonyms API
description: Using the WP Engine Smart Search Synonyms API
url: https://developers.wpengine.com/docs/smart-search/graphql-api/synonyms/
image: https://developers.wpengine.com/og/docs/smart-search/graphql-api/synonyms.png
---

# Using the Synonyms API

The Synonyms API allows you to create and manage synonym rules that improve search result relevancy. Synonyms are automatically applied to all searches once configured.

## Authentication

Clients calling the API must include an authentication header containing a valid write-access token. See the [Getting Started guide](https://developers.wpengine.com/docs/smart-search/getting-started/#authentication-credentials) for details on obtaining your tokens from the WP Engine User Portal.

```
Authorization: Bearer {ACCESS_TOKEN}
```

> **Use Full Access Token or API Key**
>
> The Synonyms API requires write access. WP Engine hosting customers must use the **Access Token**, not the **Search Token**. Non-hosting customers should use their **API Key** with Full Access permission.

## Synonym Formats

There are two supported formats for defining synonym rules: equivalent (bidirectional) and explicit (one-way) mappings.

### Equivalent Synonyms (Bidirectional)

Comma-separated terms are treated as equivalent in all directions.

```graphql
mutation EquivalentSynonyms {
  config {
    synonyms {
      saveRule(synonyms: "laptop, notebook, computer") {
        code
        success
        rule {
          id
          synonyms
        }
      }
    }
  }
}
```

### Explicit Mapping (One-way)

Use the `=>` operator to map multiple terms to a single canonical term. All terms on the left side of `=>` map one-way to the term(s) on the right.

```graphql
mutation ExplicitMapping {
  config {
    synonyms {
      saveRule(synonyms: "spinach, potato => cucumber") {
        code
        success
        rule {
          id
          synonyms
        }
      }
    }
  }
}
```

In the example above, both “spinach” and “potato” map to “cucumber”:

- Searching for “spinach” will match documents containing “cucumber”
- Searching for “potato” will match documents containing “cucumber”
- Searching for “cucumber” will NOT match documents containing “spinach” or “potato”

## Creating Synonym Rules

Create a new synonym rule using the `saveRule` mutation. The ID is auto-generated if not provided.

```graphql
mutation CreateSynonym {
  config {
    synonyms {
      saveRule(synonyms: "laptop, notebook, computer") {
        code
        success
        message
        rule {
          id
          synonyms
        }
      }
    }
  }
}
```

Response

```json
{
  "data": {
    "config": {
      "synonyms": {
        "saveRule": {
          "code": "200",
          "success": true,
          "message": "Synonym rule saved successfully",
          "rule": {
            "id": "local-abc123",
            "synonyms": "laptop, notebook, computer"
          }
        }
      }
    }
  }
}
```

> **First Synonym May Cause Brief Downtime**
>
> The first synonym rule you create on an index will cause a brief downtime (typically a few seconds) as the index is closed and reopened to enable synonym support. Subsequent synonym additions or updates do not require index downtime.

## Updating Synonym Rules

Update an existing synonym rule by providing its ID.

```graphql
mutation UpdateSynonym {
  config {
    synonyms {
      saveRule(id: "laptops", synonyms: "laptop, notebook, computer, pc") {
        code
        success
        message
        rule {
          id
          synonyms
        }
      }
    }
  }
}
```

## Listing Synonym Rules

Retrieve all synonym rules. Pagination parameters (`offset` and `limit`) are optional.

- [With Pagination](https://developers.wpengine.com/docs/smart-search/graphql-api/synonyms/#tab-panel-0-0)
- [Without Pagination](https://developers.wpengine.com/docs/smart-search/graphql-api/synonyms/#tab-panel-0-1)

```graphql
query ListSynonyms {
  config {
    synonyms {
      rules(offset: 0, limit: 10) {
        total
        offset
        limit
        rules {
          id
          synonyms
        }
      }
    }
  }
}
```

Response

```json
{
  "data": {
    "config": {
      "synonyms": {
        "rules": {
          "total": 2,
          "offset": 0,
          "limit": 10,
          "rules": [
            {
              "id": "local-d2w8az",
              "synonyms": "laptop, notebook, computer"
            },
            {
              "id": "local-p2uj1m",
              "synonyms": "spinach, potato => cucumber"
            }
          ]
        }
      }
    }
  }
}
```

## Getting a Single Synonym Rule

Retrieve a specific synonym rule by its ID.

```graphql
query GetSynonym {
  config {
    synonyms {
      rule(id: "local-d2w8az") {
        id
        synonyms
      }
    }
  }
}
```

Response

```json
{
  "data": {
    "config": {
      "synonyms": {
        "rule": {
          "id": "local-d2w8az",
          "synonyms": "laptop, notebook, computer"
        }
      }
    }
  }
}
```

## Deleting Synonym Rules

- [Delete Single Rule](https://developers.wpengine.com/docs/smart-search/graphql-api/synonyms/#tab-panel-1-0)
- [Delete All Rules](https://developers.wpengine.com/docs/smart-search/graphql-api/synonyms/#tab-panel-1-1)

```graphql
mutation DeleteSynonym {
  config {
    synonyms {
      deleteRule(id: "local-p2uj1m") {
        code
        success
        message
      }
    }
  }
}
```

## Synonym Constraints

| Constraint             | Value |
| ---------------------- | ----- |
| **Max words per rule** | 32    |
| **Min terms required** | 2     |
| **Access level**       | FULL  |

## Complete GraphQL Example (Create Synonyms / Index and Search)

### 1. Create Synonym Rules

```graphql
mutation CreateSynonyms {
  config {
    synonyms {
      laptop: saveRule(synonyms: "laptop, notebook, computer") {
        code
        success
        message
        rule {
          id
          synonyms
        }
      }


      brands: saveRule(synonyms: "iphone, ipad => apple") {
        code
        success
        message
        rule {
          id
          synonyms
        }
      }
    }
  }
}
```

Response

```json
{
  "data": {
    "config": {
      "synonyms": {
        "laptop": {
          "code": "200",
          "success": true,
          "message": "Synonym rule saved successfully",
          "rule": {
            "id": "local-abc123",
            "synonyms": "laptop, notebook, computer"
          }
        },
        "brands": {
          "code": "200",
          "success": true,
          "message": "Synonym rule saved successfully",
          "rule": {
            "id": "local-xyz789",
            "synonyms": "iphone, ipad => apple"
          }
        }
      }
    }
  }
}
```

### 2. Index Document

```graphql
mutation IndexProduct($input: DocumentInput!) {
  index(input: $input) {
    success
    document {
      id
      data
    }
  }
}
```

Variables

```json
{
  "input": {
    "data": {
      "ID": 1,
      "post_title": "MacBook Pro",
      "post_content": "Latest laptop from Apple",
      "post_type": "product",
      "post_status": "publish"
    }
  }
}
```

Response

```json
{
  "data": {
    "index": {
      "success": true,
      "document": {
        "id": "product:1",
        "data": {
          "ID": 1,
          "post_title": "MacBook Pro",
          "post_content": "Latest laptop from Apple",
          "post_type": "product",
          "post_status": "publish"
        }
      }
    }
  }
}
```

### 3. Search with Synonyms

Synonyms automatically apply to all searches.

Search Query

```graphql
query SearchWithSynonyms {
  find(query: "notebook") {
    total
    documents {
      id
      data
    }
  }
}
```

Response

```json
{
  "data": {
    "find": {
      "total": 1,
      "documents": [
        {
          "id": "product:1",
          "data": {
            "post_title": "MacBook Pro",
            "post_content": "Latest laptop from Apple"
          }
        }
      ]
    }
  }
}
```

The search for “notebook” matches the document containing “laptop” due to the synonym rule.

## Common Use Cases

- [E-commerce](https://developers.wpengine.com/docs/smart-search/graphql-api/synonyms/#tab-panel-2-0)
- [Regional Spelling](https://developers.wpengine.com/docs/smart-search/graphql-api/synonyms/#tab-panel-2-1)
- [Content Types](https://developers.wpengine.com/docs/smart-search/graphql-api/synonyms/#tab-panel-2-2)

```graphql
mutation ECommerceSynonyms {
  config {
    synonyms {
      laptop: saveRule(synonyms: "laptop, notebook, computer") {
        code
        success
      }
      mobile: saveRule(synonyms: "phone, mobile, smartphone") {
        code
        success
      }
      brands: saveRule(synonyms: "iphone, ipad => apple") {
        code
        success
      }
    }
  }
}
```

## Error Responses

### Too Many Words

```json
{
  "data": {
    "config": {
      "synonyms": {
        "saveRule": {
          "code": "400",
          "success": false,
          "message": "Synonym rule exceeds maximum of 32 words"
        }
      }
    }
  }
}
```

### Insufficient Terms

```json
{
  "data": {
    "config": {
      "synonyms": {
        "saveRule": {
          "code": "400",
          "success": false,
          "message": "Synonym rule must contain at least 2 terms"
        }
      }
    }
  }
}
```

### Invalid Authentication

```json
{
  "errors": [
    {
      "message": "Unauthorized: Full access token required",
      "extensions": { "code": "UNAUTHORIZED" }
    }
  ]
}
```

## Was this helpful?

Thanks for the feedback!

```json
{"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://developers.wpengine.com/#website","name":"WP Engine Product Documentation","url":"https://developers.wpengine.com/","description":"Resources for developing, deploying, and scaling on WP Engine.","inLanguage":"en-US","keywords":["API documentation","product documentation","headless WordPress","managed WordPress hosting"],"publisher":{"@id":"https://wpengine.com/#organization"}}]}
```