« API Reference Analytics APIs »
Elastic Docs › ›API Reference

Adaptive relevance API reference (beta)

edit

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:

Suggestions

edit

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 engine

edit

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 parameters
edit
enterprise-search-base-url (required)

The Enterprise Search base URL for your deployment.

engine (required)

The engine name.

Request body
edit
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 body
edit
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.

Examples
edit

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 query

edit

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 parameters
edit
enterprise-search-base-url (required)

The Enterprise Search base URL for your deployment.

engine (required)

The engine name.

Request body
edit
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 body
edit
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.

Examples
edit

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 engine

edit

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 parameters
edit
enterprise-search-base-url (required)

The Enterprise Search base URL for your deployment.

engine (required)

The engine name.

Request body
edit

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 body
edit

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.

Examples
edit

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.

Settings

edit

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 engine

edit

View the adaptive relevance settings for a given engine.

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

Path parameters
edit
enterprise-search-base-url (required)

The Enterprise Search base URL for your deployment.

engine (required)

The engine name.

Response body
edit

See Update settings for an engine, Request body.

Examples
edit

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 engine

edit

Update the adaptive relevance settings for a given engine.

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

Path parameters
edit
enterprise-search-base-url (required)

The Enterprise Search base URL for your deployment.

engine (required)

The engine name.

Request body
edit
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
Response body
edit

See Update settings for an engine, Request body.

Examples
edit

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 process

edit

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 suggestions

edit

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 parameters
edit
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.
Examples
edit

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'
« API Reference Analytics APIs »