Adaptive relevance API reference (beta)edit

The adaptive relevance API is a beta feature. Beta features are subject to change and are not covered by the support SLA of general release (GA) features. Elastic plans to promote this feature to GA in a future release.

The adaptive relevance API is not available at all Elastic subscription levels. Refer to the Elastic subscriptions pages for Elastic Cloud and self-managed deployments.

Manage adaptive relevance suggestions and settings with the following API endpoints:

Suggestionsedit

App Search uses adaptive relevance to suggest relevance improvements for specific queries. Use the following adaptive relevance API endpoints to view and update those suggestions:

List suggestions for an engineedit

List the adaptive relevance suggestions for a given engine.

GET <ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/<engine>/adaptive_relevance/suggestions
POST <ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/<engine>/adaptive_relevance/suggestions

Path parametersedit
enterprise-search-base-url (required)

The Enterprise Search base URL for your deployment.

engine (required)

The engine name.

Request bodyedit
filters (optional)

Wrapper for filter parameters type and status. When both are provided, results must match both filters (AND of both filters).

filters.type (optional)

The type of adaptive relevance suggestions. Must be one of the following string values:

  • curation
  • Additional types are planned for future releases
filters.status (optional)

Array of statuses for the adaptive relevance suggestions. Each array value must be one of the following strings:

  • pending
  • applied
  • automated
  • rejected
  • disabled
Response bodyedit
query

The query affected by adaptive relevance.

type

The type of adaptive relevance suggestion. Currently limited to curation.

status

The status of the adaptive relevance suggestion. One of:

  • pending
  • applied
  • automated
  • rejected
  • disabled
updated_at

Timestamp of the last update made to the suggestion.

created_at

Timestamp of the suggestion creation date and time.

promoted

Array of document identifiers that are promoted by the suggestion.

operation

Identifies the operation to perform on the curation. One of:

  • create
  • update
  • delete
curation_id

The identifier of the curation that:

  • Will be affected by the operation (for pending suggestions)
  • Has been affected by the the operation (for all other statuses)
override_manual_curation

true in case applying the operation will override a manually created or updated curation. It won’t be present in the response otherwise. Applies when suggestion status is pending.

Examplesedit

Request all adaptive relevance suggestions for an engine:

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/national-parks-demo/adaptive_relevance/suggestions' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8'

Response:

{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 2,
      "size": 25
    }
  },
  "results": [
    {
      "query": "forest",
      "type": "curation",
      "status": "pending",
      "updated_at": "2021-09-02T07:22:23Z",
      "created_at": "2021-09-02T07:22:23Z",
      "promoted": [
        "park_everglades",
        "park_american-samoa",
        "park_arches"
      ],
      "operation": "create"
    },
    {
      "query": "park",
      "type": "curation",
      "status": "pending",
      "updated_at": "2021-10-22T07:34:12Z",
      "created_at": "2021-10-22T07:34:54Z",
      "promoted": [
        "park_yellowstone"
      ],
      "operation": "create",
      "override_manual_curation": true
    },
    {
      "query": "park",
      "type": "curation",
      "status": "applied",
      "updated_at": "2021-09-02T07:22:23Z",
      "created_at": "2021-09-02T07:22:23Z",
      "promoted": [
        "park_death-valley",
        "park_great-basin"
      ],
      "operation": "update",
      "curation_id": "cur-432fef923412a"
    }
  ]
}

Request adaptive relevance suggestions for an engine, filtering by status:

curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/national-parks-demo/adaptive_relevance/suggestions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "filters": {
    "status": ["pending", "applied"]
  }
}'

Request adaptive relevance suggestions for an engine, filtering by adaptive relevance suggestion type:

curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/national-parks-demo/adaptive_relevance/suggestions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "filters": {
    "type": "curation"
  }
}'

List suggestions for an engine and queryedit

List the adaptive relevance suggestions for a given engine and query.

GET <ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/<engine>/adaptive_relevance/suggestions/<query>
POST <ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/<engine>/adaptive_relevance/suggestions/<query>

Path parametersedit
enterprise-search-base-url (required)

The Enterprise Search base URL for your deployment.

engine (required)

The engine name.

Request bodyedit
filters (optional)

Wrapper for filter parameters type and status. When both are provided, results must match both filters (AND of both filters).

filters.type (optional)

The type of adaptive relevance suggestions. Must be one of the following string values:

  • curation
  • Additional types are planned for future releases.
filters.status (optional)

Array of statuses for the adaptive relevance suggestions. Each array value must be one of the following strings:

  • pending
  • applied
  • automated
  • rejected
  • disabled
Response bodyedit
query

The query affected by adaptive relevance.

type

The type of adaptive relevance suggestion. Currently limited to curation.

status

The status of the adaptive relevance suggestion. One of:

  • pending
  • applied
  • automated
  • rejected
  • disabled
updated_at

Timestamp of the last update made to the suggestion.

created_at

Timestamp of the suggestion creation date and time.

promoted

Array of document identifiers that are promoted by the suggestion.

operation

Identifies the operation to perform on the curation. One of:

  • create
  • update
  • delete
curation_id

The identifier of the curation that:

  • Will be affected by the operation (for pending suggestions)
  • Has been affected by the the operation (for all other statuses)
override_manual_curation

true in case applying the operation will override a manually created or updated curation. It won’t be present in the response otherwise. Applies when suggestion status is pending.

Examplesedit

Request all adaptive relevance suggestions for an engine and query:

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/national-parks-demo/adaptive_relevance/suggestions/forest' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8'

Response:

{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 1,
      "size": 25
    }
  },
  "results": [
    {
      "query": "forest",
      "type": "curation",
      "status": "pending",
      "updated_at": "2021-09-02T07:22:23Z",
      "created_at": "2021-09-02T07:22:23Z",
      "promoted": [
        "park_everglades",
        "park_american-samoa",
        "park_arches"
      ],
      "operation": "create"
    }
  ]
}

Request adaptive relevance suggestions for an engine and query, filtering by status:

curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/national-parks-demo/adaptive_relevance/suggestions/forest' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
"filters": {
"status": ["pending", "applied"]
}
}'

Request adaptive relevance suggestions for an engine and query, filtering by adaptive relevance suggestion type:

curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/national-parks-demo/adaptive_relevance/suggestions/forest' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "filters": {
    "type": "curation"
  }
}'

Update suggestions for an engineedit

Update the status of one or more suggestions for an engine.

PUT <ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/<engine>/adaptive_relevance/suggestions

Path parametersedit
enterprise-search-base-url (required)

The Enterprise Search base URL for your deployment.

engine (required)

The engine name.

Request bodyedit

The request body contains an array of suggestion updates. Each suggestion update contains the following parameters:

query

The query that identifies the adaptive relevance suggestion to update.

type

The type of adaptive relevance suggestion. Currently limited to curation.

status

The status that the adaptive relevance suggestion will be updated to. One of:

  • pending
  • applied
  • automated
  • rejected
  • disabled
Response bodyedit

The response body will contain a single result element with an array of suggestion results. Each suggestion result element will contain:

query

The query affected by adaptive relevance.

type

The type of adaptive relevance suggestion. Currently limited to curation.

status

The status the adaptive relevance suggestion is currently on if the request was successful. Otherwise, the status that was requested on the update request. One of:

  • pending
  • applied
  • automated
  • rejected
  • disabled
errors

If present, this field indicates that the specific request was not successful. It will contain an array of errors that will describe the problem with the update operation.

Response status code will be 200 regardless of results having errors.

The following fields will be present when the update operation has been performed successfully, and no errors have been found:

updated_at

Timestamp of the last update made to the suggestion.

created_at

Timestamp of the suggestion creation date and time.

promoted

Array of document identifiers that are promoted by the suggestion.

operation

Identifies the operation to perform on the curation. One of:

  • create
  • update
  • delete
curation_id

The identifier of the curation that:

  • Will be affected by the operation (for pending suggestions)
  • Has been affected by the the operation (for all other statuses)
override_manual_curation

true in case applying the operation will override a manually created or updated curation. It won’t be present in the response otherwise. Applies when suggestion status is pending.

Examplesedit

Request with two successful and one failed update:

curl -X PUT '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/national-parks-demo/adaptive_relevance/suggestions' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-H 'Content-Type: application/json' \
-d '[
   {
     "query" : "forest",
     "type": "curation",
     "status": "applied"
   },
   {
     "query" : "park",
     "type": "curation",
     "status": "rejected"
   },
   {
     "query" : "mountain",
     "type": "curation",
     "status": "applied"
   }
]
'

Response:

{
  "results": [
    {
      "query": "forest",
      "type": "curation",
      "status": "applied",
      "updated_at": "2021-09-02T08:12:43Z",
      "created_at": "2021-09-02T07:22:23Z",
      "promoted": [
        "park_everglades",
        "park_american-samoa",
        "park_arches"
      ],
      "operation": "create",
      "curation_id": "cur-619375156c801b"
    },
    {
      "query": "park",
      "type": "curation",
      "status": "rejected",
      "updated_at": "2021-09-02T08:12:43Z",
      "created_at": "2021-09-02T07:22:23Z",
      "promoted": [
        "park_death-valley",
        "park_great-basin"
      ],
      "operation": "create"
    },
    {
        "query": "mountain",
        "type": "curation",
        "status": "applied",
        "errors": [
            "Status 'applied' is not a valid status transition for current status 'applied'. Valid status transitions are automated, pending, disabled, and rejected"
        ]
    }
  ]
}

Response status code would be 400, as there were errors in one of the update results.

Settingsedit

Each App Search engine stores settings that determine how adaptive relevance applies to that engine. Use the following adaptive relevance API endpoints to view and update those settings:

View settings for an engineedit

View the adaptive relevance settings for a given engine.

GET <ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/<engine>/adaptive_relevance/settings

Path parametersedit
enterprise-search-base-url (required)

The Enterprise Search base URL for your deployment.

engine (required)

The engine name.

Examplesedit

Request the adaptive relevance settings for an engine:

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/national-parks-demo/adaptive_relevance/settings' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx'

Response:

{
  "curation": {
    "enabled": true,
    "mode": "manual",
    "timeframe": 7,
    "max_size": 3,
    "min_clicks": 20,
    "schedule_frequency": 1,
    "schedule_unit": "day"
  }
}

Update settings for an engineedit

Update the adaptive relevance settings for a given engine.

PUT <ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/<engine>/adaptive_relevance/settings

Path parametersedit
enterprise-search-base-url (required)

The Enterprise Search base URL for your deployment.

engine (required)

The engine name.

Request bodyedit
curation (required)

The adaptive relevance settings for the curation type. Required since curation is currently the only supported type.

curation.enabled (optional)

Boolean to determine if the adaptive relevance suggestions is turned on for the engine and curation type.

curation.mode (optional)

Must be manual or automatic. New or updated suggestions are automatically applied if automatic. Otherwise, the suggestions need to be applied via UI or API. manual by default.

curation.timeframe (optional)

Integer to determine the number of days worth of logs to use for the adaptive relevance suggestions analysis. Defaults to 7.

curation.max_size (optional)

Maximum number of promoted documents that will be suggested. Defaults to 3.

curation.min_clicks (optional)

Minimum number of clicks for a document to be considered as significant for promotion. Defaults to 20.

curation.schedule_frequency (optional)

Integer value used with schedule_unit to determine how frequently to run adaptive relevance suggestions analysis. Defaults to 1.

curation.schedule_unit (optional)

Value used with schedule_frequency to determine how frequently to run adaptive relevance suggestions analysis. Defaults to day. Must be one of:

  • second
  • minute
  • hour
  • day
  • week
  • month
Examplesedit

Turn off adaptive relevance suggestions for an engine:

curl -X PUT '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/national-parks-demo/adaptive_relevance/settings' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \
-d '{ "enabled": false }'

Response:

{
  "curation": {
    "enabled": false,
    "mode": "manual",
    "timeframe": 7,
    "max_size": 3,
    "min_clicks": 20,
    "schedule_frequency": 1,
    "schedule_unit": "day"
  }
}

Turn on automatic adaptive relevance suggestions for an engine:

curl -X PUT '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/national-parks-demo/adaptive_relevance/settings' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \
-d '{"curation":{"mode":"automatic"}}'

Response:

{
  "curation": {
    "enabled": true,
    "mode": "automatic",
    "timeframe": 7,
    "max_size": 3,
    "min_clicks": 20,
    "schedule_frequency": 1,
    "schedule_unit": "day"
  }
}

Suggestions update processedit

Suggestions are updated for each engine using an update process, that runs on a schedule defined in Settings. This API enables operations on the suggestions update process.

Refresh suggestionsedit

Refreshes the engine suggestions for a specific suggestion type, making the update process to run immediately in case it is not already running.

POST <ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/<engine>}/adaptive_relevance/update_process/<suggestion_type>/refresh

Path parametersedit
enterprise-search-base-url (required)

The Enterprise Search base URL for your deployment.

engine (required)

The engine name.

suggestion_type (required)

The type of adaptive relevance suggestions. Must be one of the following string values:

  • curation
  • Additional types are planned for future releases.
Examplesedit

Run update process for curation suggestion types:

curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v0/engines/national-parks-demo/adaptive_relevance/update_process/curation/refresh' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx'