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:

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.

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
}