Synonyms API

The Synonyms API manages the set of synonyms defined in Solr for a collection:

  • a string of terms that will expand on the terms the user entered, like Television, TV.

  • a term that should be mapped to another term, like i-pod⇒ipod.

When updating the synonyms, note that only PUT requests are supported, and any new data sent will overwrite the previous synonyms. As such, PUT requests can be seen as replacement requests.

It is only possible to have a single set of stop words when using this REST API. If you need different sets of stop words for different field types (perhaps for different languages), you will need to edit the schema.xml and manually manage the stop word files.

List or Update Synonyms

The path for this request is:


where <collectionName> is the name of an specific collection.

A GET request will return the synonym definitions in JSON format. A PUT request will replace the existing synonyms with the new list.

These endpoints also allow for import and export of the synonyms list. To download the list, replace the Content-Type in the GET request to "`Accept: application/octet-stream"`. To upload a file, you can emulate an HTTP form with cURL’s "-form" option, as in -form file=@synonyms.txt.


Property Description


The terms that should be matched from the user input.

When defining synonyms that should expand on the user’s input, simply enter all of the terms as values of this property separated by commas.

When defining synonyms where one or more terms should map to another term, only enter the term(s) to be mapped as the values for this property.


The terms that should replace the user input. This property is only used when mapping terms entered by the user to another term.


A GET request will return the current synonym list, in JSON format.

No data will be returned for a PUT request.


Use port 8765 in local development environments only. In production, use port 8764.

Update the synonym list with a new list of synonyms for a collection named 'docs':


curl -u user:pass -X PUT -H 'Content-type: application/json' -d '[{"match":[ "GB","gib","gigabyte","gigabytes" ]}, {"match": ["MB","mib","megabyte","megabytes"]}, {"match" : ["Television","Televisions","TV","TVs"]},{"match":["foo"],"replace":["bar"]}]' http://localhost:8764/api/apollo/synonyms/docs



List the current synonyms list:


curl -u user:pass http://localhost:8764/api/apollo/synonyms/docs


[ {
  "match" : [ "GB", "gib", "gigabyte", "gigabytes" ]
}, {
  "match" : [ "MB", "mib", "megabyte", "megabytes" ]
}, {
  "match" : [ "Television", "Televisions", "TV", "TVs" ]
}, {
  "match" : [ "foo" ],
  "replace" : [ "bar" ]
}, {
  "match" : [ "i-pod" ],
  "replace" : [ "ipod" ]
} ]

Upload a synonyms list:


curl -u user:pass -X PUT --form file=@synonyms.txt http://localhost:8764/api/apollo/synonyms/docs



Download a synonyms list, and save it as a file named "synonyms.txt":


curl -u user:pass -H "Accept: application/octet-stream" http://localhost:8764/api/apollo/synonyms/docs > synonyms.txt