search mobile facets autocomplete spellcheck crawler rankings weights synonyms analytics engage api customize documentation install setup technology content domains user history info home business cart chart contact email activate analyticsalt analytics autocomplete cart contact content crawling custom documentation domains email engage faceted history info install mobile person querybuilder search setup spellcheck synonyms weights engage_search_term engage_related_content engage_next_results engage_personalized_results engage_recent_results success add arrow-down arrow-left arrow-right arrow-up caret-down caret-left caret-right caret-up check close content conversions-small conversions details edit grid help small-info error live magento minus move photo pin plus preview refresh search settings small-home stat subtract text trash unpin wordpress x alert case_deflection advanced-permissions keyword-detection predictive-ai sso
App Search Documentation / app search: Synonyms
Synonyms

From Zero to Search

Guides

API Reference

App Search API Clients

Self-Managed App Search

Resources

Synonyms

Checkout the Synonyms guide for deeper concepts.


Create synonym sets.

Authentication

For authentication, the Synonyms endpoint requires...

  1. A Host Identifier: [HOST_IDENTIFIER]
  2. The name of your Engine: [ENGINE]
  3. A Private API Key: [PRIVATE_API_KEY]
curl -X GET 'https://[HOST_IDENTIFIER].api.swiftype.com/api/as/v1/engines/[ENGINE]/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer [PRIVATE_API_KEY]'

List Synonyms

List All Synonyms

Retrieves synonym sets for an Engine.

GET /api/as/v1/engines/{ENGINE_NAME}/synonyms
page
optional
A JSON object containing current and size, where current is the current page number and size is the page size. The maximum for size is 25, and be will truncated if a larger size is requested. The default is the first page of synonym sets with pagination at 25.
Example - A GET request for all synonyms, paginated. Returns the 2nd page of results, with 20 results per page. 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response 
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 3,
      "size": 25
    }
  },
  "results": [
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "park",
        "trail"
      ]
    },
    {
      "id": "syn-5b11ac72c9f9296b35220ac9",
      "synonyms": [
        "protected",
        "heritage"
      ]
    },
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "hectares",
        "acres"
      ]
    }
  ]
}

Example - A GET request for all synonyms, paginated. Returns the 2nd page of results, with 20 results per page.
No Java example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Java example available, showing cURL 
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 3,
      "size": 25
    }
  },
  "results": [
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "park",
        "trail"
      ]
    },
    {
      "id": "syn-5b11ac72c9f9296b35220ac9",
      "synonyms": [
        "protected",
        "heritage"
      ]
    },
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "hectares",
        "acres"
      ]
    }
  ]
}

Example - A GET request for all synonyms, paginated. Returns the 2nd page of results, with 20 results per page.
No Node example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Node example available, showing cURL 
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 3,
      "size": 25
    }
  },
  "results": [
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "park",
        "trail"
      ]
    },
    {
      "id": "syn-5b11ac72c9f9296b35220ac9",
      "synonyms": [
        "protected",
        "heritage"
      ]
    },
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "hectares",
        "acres"
      ]
    }
  ]
}

Example - A GET request for all synonyms, paginated. Returns the 2nd page of results, with 20 results per page.
No Ruby example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Ruby example available, showing cURL 
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 3,
      "size": 25
    }
  },
  "results": [
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "park",
        "trail"
      ]
    },
    {
      "id": "syn-5b11ac72c9f9296b35220ac9",
      "synonyms": [
        "protected",
        "heritage"
      ]
    },
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "hectares",
        "acres"
      ]
    }
  ]
}

Example - A GET request for all synonyms, paginated. Returns the 2nd page of results, with 20 results per page.
No Python example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Python example available, showing cURL 
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 3,
      "size": 25
    }
  },
  "results": [
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "park",
        "trail"
      ]
    },
    {
      "id": "syn-5b11ac72c9f9296b35220ac9",
      "synonyms": [
        "protected",
        "heritage"
      ]
    },
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "hectares",
        "acres"
      ]
    }
  ]
}

Example - A GET request for all synonyms, paginated. Returns the 2nd page of results, with 20 results per page.
No Javascript example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Javascript example available, showing cURL 
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 3,
      "size": 25
    }
  },
  "results": [
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "park",
        "trail"
      ]
    },
    {
      "id": "syn-5b11ac72c9f9296b35220ac9",
      "synonyms": [
        "protected",
        "heritage"
      ]
    },
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "hectares",
        "acres"
      ]
    }
  ]
}

List All Synonyms with Pagination

Example 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "size": 20,
    "current": 2
  }
}'
Example Response 
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 2,
      "total_results": 30,
      "size": 20
    }
  },
  "results": [
    ## Truncated!
  ]
}

Example
No Java example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "size": 20,
    "current": 2
  }
}'
Example Response
No Java example available, showing cURL 
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 2,
      "total_results": 30,
      "size": 20
    }
  },
  "results": [
    ## Truncated!
  ]
}

Example
No Node example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "size": 20,
    "current": 2
  }
}'
Example Response
No Node example available, showing cURL 
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 2,
      "total_results": 30,
      "size": 20
    }
  },
  "results": [
    ## Truncated!
  ]
}

Example
No Ruby example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "size": 20,
    "current": 2
  }
}'
Example Response
No Ruby example available, showing cURL 
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 2,
      "total_results": 30,
      "size": 20
    }
  },
  "results": [
    ## Truncated!
  ]
}

Example
No Python example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "size": 20,
    "current": 2
  }
}'
Example Response
No Python example available, showing cURL 
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 2,
      "total_results": 30,
      "size": 20
    }
  },
  "results": [
    ## Truncated!
  ]
}

Example
No Javascript example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "size": 20,
    "current": 2
  }
}'
Example Response
No Javascript example available, showing cURL 
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 2,
      "total_results": 30,
      "size": 20
    }
  },
  "results": [
    ## Truncated!
  ]
}

Lists a Single Synonym

Retrieves a synonym set by id.

GET /api/as/v1/engines/{ENGINE_NAME}/synonyms/{SYNONYM_SET_ID}
Example 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac66c9f9292013220ad3' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response 
{
  "id": "syn-5b11ac66c9f9292013220ad3",
  "synonyms": [
    "park",
    "trail"
  ]
}

Example
No Java example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac66c9f9292013220ad3' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Java example available, showing cURL 
{
  "id": "syn-5b11ac66c9f9292013220ad3",
  "synonyms": [
    "park",
    "trail"
  ]
}

Example
No Node example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac66c9f9292013220ad3' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Node example available, showing cURL 
{
  "id": "syn-5b11ac66c9f9292013220ad3",
  "synonyms": [
    "park",
    "trail"
  ]
}

Example
No Ruby example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac66c9f9292013220ad3' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Ruby example available, showing cURL 
{
  "id": "syn-5b11ac66c9f9292013220ad3",
  "synonyms": [
    "park",
    "trail"
  ]
}

Example
No Python example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac66c9f9292013220ad3' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Python example available, showing cURL 
{
  "id": "syn-5b11ac66c9f9292013220ad3",
  "synonyms": [
    "park",
    "trail"
  ]
}

Example
No Javascript example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac66c9f9292013220ad3' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Javascript example available, showing cURL 
{
  "id": "syn-5b11ac66c9f9292013220ad3",
  "synonyms": [
    "park",
    "trail"
  ]
}

Create a Synonym Set

Creates a new synonym set for an Engine.

You may only create one set of synonyms per API call.

The endpoint will not accept an array of arrays!

A synonym set can contain up to 32 words.

POST /api/as/v1/engines/{ENGINE_NAME}/synonyms
synonyms
required
An array of strings containing at least two unique strings.
Example 
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["park", "trail"]
}'
Example Response 
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "park",
    "trail"
  ]
}

Example
No Java example available, showing cURL 
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["park", "trail"]
}'
Example Response
No Java example available, showing cURL 
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "park",
    "trail"
  ]
}

Example
No Node example available, showing cURL 
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["park", "trail"]
}'
Example Response
No Node example available, showing cURL 
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "park",
    "trail"
  ]
}

Example
No Ruby example available, showing cURL 
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["park", "trail"]
}'
Example Response
No Ruby example available, showing cURL 
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "park",
    "trail"
  ]
}

Example
No Python example available, showing cURL 
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["park", "trail"]
}'
Example Response
No Python example available, showing cURL 
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "park",
    "trail"
  ]
}

Example
No Javascript example available, showing cURL 
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["park", "trail"]
}'
Example Response
No Javascript example available, showing cURL 
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "park",
    "trail"
  ]
}

Update a Synonym Set

Updates an existing synonym set for an Engine by id.

You may only update one set of synonyms per API call.

The endpoint will not accept an array of arrays!

A synonym set can contain up to 32 words.

PUT /api/as/v1/engines/{ENGINE_NAME}/synonyms/{SYNONYM_SET_ID}
synonyms
required
An array of strings containing at least two unique strings.
Example 
curl -X PUT 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac72c9f9296b35220ac9' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["road", "trail"]
}'
Example Response 
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "road",
    "trail"
  ]
}

Example
No Java example available, showing cURL 
curl -X PUT 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac72c9f9296b35220ac9' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["road", "trail"]
}'
Example Response
No Java example available, showing cURL 
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "road",
    "trail"
  ]
}

Example
No Node example available, showing cURL 
curl -X PUT 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac72c9f9296b35220ac9' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["road", "trail"]
}'
Example Response
No Node example available, showing cURL 
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "road",
    "trail"
  ]
}

Example
No Ruby example available, showing cURL 
curl -X PUT 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac72c9f9296b35220ac9' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["road", "trail"]
}'
Example Response
No Ruby example available, showing cURL 
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "road",
    "trail"
  ]
}

Example
No Python example available, showing cURL 
curl -X PUT 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac72c9f9296b35220ac9' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["road", "trail"]
}'
Example Response
No Python example available, showing cURL 
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "road",
    "trail"
  ]
}

Example
No Javascript example available, showing cURL 
curl -X PUT 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac72c9f9296b35220ac9' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["road", "trail"]
}'
Example Response
No Javascript example available, showing cURL 
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "road",
    "trail"
  ]
}

Delete a Synonym

Delete a synonym set by id.

DELETE /api/as/v1/engines/{ENGINE_NAME}/synonyms/{SYNONYM_SET_ID}
Example 
curl -X DELETE 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac66c9f9292013220ad3'  \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response 
{
  "deleted": true
}

Example
No Java example available, showing cURL 
curl -X DELETE 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac66c9f9292013220ad3'  \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Java example available, showing cURL 
{
  "deleted": true
}

Example
No Node example available, showing cURL 
curl -X DELETE 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac66c9f9292013220ad3'  \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Node example available, showing cURL 
{
  "deleted": true
}

Example
No Ruby example available, showing cURL 
curl -X DELETE 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac66c9f9292013220ad3'  \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Ruby example available, showing cURL 
{
  "deleted": true
}

Example
No Python example available, showing cURL 
curl -X DELETE 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac66c9f9292013220ad3'  \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Python example available, showing cURL 
{
  "deleted": true
}

Example
No Javascript example available, showing cURL 
curl -X DELETE 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac66c9f9292013220ad3'  \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Javascript example available, showing cURL 
{
  "deleted": true
}

Errors

The endpoint will return an error if:

  • The API Key does not have write permissions for the requested Engine.
  • The requested synonym set does not exist.
  • The synonym object is not well formed.
  • The request tried to create multiple synonym sets.

What's Next?

Configuring Synonyms is a useful way to guide your users to 'the right' content. It is most useful when you know the precise terms that they are searching for. For that, you should explore the Analytics and Clickthrough end-points, so that you are aware of your insightful capabilities. If you are looking to provide even more precise and curated results, venture to the Curations end-point.

Stuck? Looking for help? Contact support or check out the App Search community forum!