Synonyms API referenceedit
Provides synonym set management for Workplace Search queries.
In this API referenceedit
Synonyms API authenticationedit
Workplace Search APIs support multiple methods of authentication.
To manage synonym sets, the valid authorization must belong to a member with the Admin
role.
List synonym setsedit
GET /api/ws/v1/synonyms
List synonym sets, optionally filtered by a term or list of terms. Issuing this call
without any body parameters will default to the first page with a maximum of 25 results
per page and sorted by the updated_at
timestamp in descending order.
Body parameters can include:
|
optional |
Provides optional keys of |
|
optional |
A single term or array of terms, used to filter the synonym sets by. Term filters will perform an exact match on terms within synonym sets. |
|
optional |
Sort results |
curl -X GET '<WORKPLACE_SEARCH_BASE_URL>/api/ws/v1/synonyms' \ -H 'Authorization: Bearer <ACCESS_TOKEN>' \ -H 'Content-Type: application/json' \ -d '{ "page": { "current": "<INT>", "size": "<INT>" }, "filter": { "terms": "<STRING>|<STRING ARRAY>" }, "sort": { "created_at": "asc|desc", "updated_at": "asc|desc" } }'
{ "meta": { "page": { "current": 1, "total_pages": 1, "total_results": 10, "size": 25 }, "filter": { "terms": ["house", "books"] }, "sort": { { "updated_at": "desc" }, { "created_at": "asc" } } }, "results": [ { "id": "<ID>", "synonyms": ["house","home","abode"], "created_at": "2021-01-02T10:00:00Z", "updated_at": "2021-04-22T00:00:05Z" }, ... ] }
Show single synonym setedit
GET /api/ws/v1/synonyms/<ID>
Display a single synonym set by id.
curl -X GET '<WORKPLACE_SEARCH_BASE_URL>/api/ws/v1/synonyms/<ID>' \ -H 'Authorization: Bearer <ACCESS_TOKEN>'
{ "id": "<ID>", "synonyms": ["house","home","abode"], "created_at": "2021-01-02T10:00:00Z", "updated_at": "2021-04-22T00:00:05Z" }
Create synonym setsedit
Synonym sets can be created individually or in batches of up to 100 at a time.
Create a single synonym setedit
POST /api/ws/v1/synonyms
Provide an array of terms to create a single synonym set. If created successfully, the synonyms as well as the
new synonym set ID will be returned. If any of the terms already exist, a 400 / Bad Request
status code will be
returned along with an error message indicating which terms already exist.
curl -X POST '<WORKPLACE_SEARCH_BASE_URL>/api/ws/v1/synonyms' \ -H 'Authorization: Bearer <ACCESS_TOKEN>' \ -H 'Content-Type: application/json' \ -d '{ "synonyms": ["house", "home", "abode"] }'
{ "id": "<ID>", "synonyms": ["house","home","abode"] }
Create a batch of synonym setsedit
POST /api/ws/v1/synonyms
Provide up to 100 synonym sets to create in a single batch. For each successful set, the synonyms and the created
ID will be returned in the results. If there are any errors with any of the sets to create, the has_errors
flag
will be set to true, and any errors will be given within the individual sets.
curl -X POST '<WORKPLACE_SEARCH_BASE_URL>/api/ws/v1/synonyms' \ -H 'Authorization: Bearer <ACCESS_TOKEN>' \ -H 'Content-Type: application/json' \ -d '{ "synonym_sets": [ { "synonyms": ["house", "home", "abode"] }, { "synonyms": ["cat", "feline", "kitty"] }, { "synonyms": ["mouses", "mice"] } ] }'
{ "has_errors": true, "synonym_sets": [ { "synonyms": ["house","home","abode"], "errors": [ "Duplicate terms - the following terms already exist in an existing synonym set: house, home" ] }, { "id": "<ID>", "synonyms": ["cat","feline","kitty"] }, { "id": "<ID>", "synonyms": ["mouse","mice","meeces"] } ] }
Update a synonym setedit
PUT /api/ws/v1/synonyms/<ID>
Updates a single synonym set.
All of the terms for the set will be replaced with the provided items.
curl -X PUT '<WORKPLACE_SEARCH_BASE_URL>/api/ws/v1/synonyms/<ID>' \ -H 'Authorization: Bearer <ACCESS_TOKEN>' \ -H 'Content-Type: application/json' \ -d '{ "synonyms": ["house", "home", "dwelling"] }'
{ "id": "[ID]", "synonyms": ["house", "home", "dwelling"], "created_at": "2021-01-02T10:00:00Z", "updated_at": "2021-04-22T00:00:05Z" }
Delete a synonym setedit
DELETE /api/ws/v1/synonyms/<ID>
Deletes a single synonym set by ID.
curl -X DELETE '<WORKPLACE_SEARCH_BASE_URL>/api/ws/v1/synonyms/<ID>' \ -H 'Authorization: Bearer <ACCESS_TOKEN>'
{ "deleted": true }