IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Analytics event API reference Automatic query refinement settings »

› ›

Synonyms API reference

edit

Synonyms API reference

edit

Provides synonym set management for Workplace Search queries.

In this API reference

edit

Synonyms API authentication

edit

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 sets

edit

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:

`page`	optional	Provides optional keys of `size` and `current`. Specifies the number of results per page and which page the API should return. Defaults values are a `size` of 25 and a `current` of 1.
`filter`	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.
`sort`	optional	Sort results `asc` or `desc` on the `created_at` or `updated_at` fields.

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 set

edit

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 sets

edit

Synonym sets can be created individually or in batches of up to 100 at a time.

Create a single synonym set

edit

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 sets

edit

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 set

edit

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 set

edit

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
}

« Analytics event API reference Automatic query refinement settings »