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 for details on obtaining your tokens from the WP Engine User Portal.

Authorization: Bearer {ACCESS_TOKEN}

Use Full Access Token

The Synonyms API requires write access. You’ll need to use the “Access Token”, not the “Search Token”.

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.

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.

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.

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

Response

{
  "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.

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

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

Without Pagination

query ListAllSynonyms {
  config {
    synonyms {
      rules {
        total
        rules {
          id
          synonyms
        }
      }
    }
  }
}

Response

{
  "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.

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

Response

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

Deleting Synonym Rules

Delete Single Rule

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

Delete All Rules

mutation DeleteAllSynonyms {
  config {
    synonyms {
      deleteAllRules {
        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

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

{
  "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

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

Variables

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

Response

{
  "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

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

Response

{
  "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

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
      }
    }
  }
}

Regional Spelling

mutation RegionalSynonyms {
  config {
    synonyms {
      color: saveRule(synonyms: "color, colour") {
        code
        success
      }
      organize: saveRule(synonyms: "organize, organise") {
        code
        success
      }
    }
  }
}

Content Types

mutation ContentSynonyms {
  config {
    synonyms {
      articles: saveRule(synonyms: "article, post, blog") {
        code
        success
      }
      tutorials: saveRule(synonyms: "tutorial, guide, howto") {
        code
        success
      }
    }
  }
}

Error Responses

Too Many Words

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

Insufficient Terms

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

Invalid Authentication

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