IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Credentials API Documents API »
Elastic Docs › ›API Reference

Curations API reference

edit

Curations API reference

edit

Curations allow search operators to customize search results for specific queries using promoted documents and hidden documents.

Use the following API operations to manage curations:

These operations share the same access requirements.

Access

edit

To access curations API operations, you’ll need:

  • The name of your engine: <engine>
  • A private API key: <key> 
curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/<engine>/curations' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <key>'

List all curations for an engine

edit

Return all curations for a given engine.

GET <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/<engine>/curations

Path parameters

edit
enterprise-search-base-url (required)

The Enterprise Search base URL for your deployment.

engine (required)

The engine name.

Query parameters

edit
page[current] (optional)

Integer value to specify the results page number to display.

page[size] (optional)

Integer value that determines the results page size. Defaults to 25 per page.

Request body

edit
page (optional)

Pagination settings can be specified as request body instead of using query parameters.

page.current (optional)

Integer value to specify the results page number to display.

page.size (optional)

Integer value to specify the results page number to display.

Response body

edit

Response body will contain an array of results under the result element, each with the following fields:

id

Curation identifier.

queries

Array of queries for which the curation modifies results.

promoted

Array of document identifiers that the specified queries will return as top results. The document identifiers are ordered according to the order in which they will be returned in results. In case it is an empty array, top results for the queries will not be modified by the curation.

hidden

Array of document identifiers that the curation will never return as results for the specified queries. In case it is an empty array, no result for the queries will be hidden by the curation.

suggestion

Associated suggestion for the curation. This field will only be present in case there is an adaptive relevance suggestion associated to the curation. See Adaptive relevance API reference (beta) for additional details.

suggestion.status

The status of the adaptive relevance suggestion. One of:

  • pending
  • applied
  • automated
  • rejected
  • disabled
suggestion.updated_at

Timestamp of the last update made to the suggestion.

suggestion.created_at

Timestamp of the suggestion creation date and time.

suggestion.promoted

Array of document identifiers that are promoted by the suggestion.

suggestion.operation

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

  • create
  • update
  • delete

Examples

edit

Request all curations for an engine:

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

Response:

{
    "meta": {
        "page": {
            "current": 1,
            "total_pages": 1,
            "total_results": 2,
            "size": 25
        }
    },
    "results": [
        {
            "id": "cur-61929ad3077aeebab87bb4c5",
            "queries": [
                "mountains"
            ],
            "promoted": [
                "park_glacier",
                "park_rocky-mountain"
            ],
            "hidden": []
        },
        {
            "id": "cur-61929ad2077aeebab87bb4c4",
            "queries": [
                "hiking"
            ],
            "promoted": [
                "park_shenandoah"
            ],
            "hidden": ["park_lake-clark"],
            "suggestion": {
                "created_at": "2021-11-16T09:07:38Z",
                "operation": "create",
                "promoted": [
                    "park_yellowstone"
                ],
                "status": "pending",
                "updated_at": "2021-11-16T11:35:39Z"
            }
        }
    ]
}

View a curation

edit

Retrieves information for a specific curation.

GET <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/<engine>/curations/<curation_id>

Path parameters

edit
enterprise-search-base-url (required)

The Enterprise Search base URL for your deployment.

engine (required)

The engine name.

curation_id (required)

The curation identifier.

Response body

edit
id

Curation identifier

queries

Array of queries for which the curation modifies results.

promoted

Array of document identifiers that the specified queries will return as top results. The document identifiers are ordered according to the order in which they will be returned in results. In case it is an empty array, top results for the queries will not be modified by the curation.

hidden

Array of document identifiers that the curation will never return as results for the specified queries. In case it is an empty array, no result for the queries will be hidden by the curation.

suggestion

Associated suggestion for the curation. This field will only be present in case there is an adaptive relevance suggestion associated to the curation. See Adaptive relevance API reference (beta) for additional details.

suggestion.status

The status of the adaptive relevance suggestion. One of:

  • pending
  • applied
  • automated
  • rejected
  • disabled
suggestion.updated_at

Timestamp of the last update made to the suggestion.

suggestion.created_at

Timestamp of the suggestion creation date and time.

suggestion.promoted

Array of document identifiers that are promoted by the suggestion.

suggestion.operation

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

  • create
  • update
  • delete

Examples

edit

Request a single curation for an engine:

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/curations/cur-61929ad2077aeebab87bb4c4' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8'

Response:

{
    "id": "cur-61929ad2077aeebab87bb4c4",
    "queries": [
        "hiking"
    ],
    "promoted": [
        "park_shenandoah"
    ],
    "hidden": ["park_lake-clark"],
    "suggestion": {
        "created_at": "2021-11-16T09:07:38Z",
        "operation": "create",
        "promoted": [
            "park_yellowstone"
        ],
        "status": "pending",
        "updated_at": "2021-11-16T11:35:39Z"
    }
}

Create a curation

edit

Creates a new curation for one or more queries.

POST <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/<engine>/curations

Path parameters

edit
enterprise-search-base-url (required)

The Enterprise Search base URL for your deployment.

engine (required)

The engine name.

Request body

edit
queries

Array of queries for which the curation modifies results.

promoted

Array of document identifiers that the specified queries will return as top results. The document identifiers are ordered according to the order in which they will be returned in results. In case it is an empty array, top results for the queries will not be modified by the curation.

For meta engines, see Document IDs for meta engines

hidden

Array of document identifiers that the curation will never return as results for the specified queries. In case it is an empty array, no result for the queries will be hidden by the curation.

For meta engines, see Document IDs for meta engines

Response body

edit
id

Identifier for the newly created curation.

Examples

edit

Create a new curation for an engine with both promoted and hidden documents:

curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/curations' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-H 'Content-Type: application/json' \
-d '{
    "queries": [
        "park"
    ],
    "promoted": [
        "park_gates-of-the-arctic",
        "park_zion"
    ],
    "hidden": [
        "park_olympic",
        "park_katmai"
    ]
}'

Response:

{
    "id": "cur-6193db496c801b95a3cf46e3"
}

Update a curation

edit

Updates a curation for an engine.

PUT <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/<engine>/curations/<curation_id>

A curation that has an associated suggestion in automated status cannot be updated via the API. This is done in order to prevent the interference with an already established automated suggestion.

In order to update a suggestion that has been automated, change its status to applied so it gets converted to a manual suggestion first. Then, update the curation via the API.

Manually updating a curation is equivalent to rejecting the proposed suggestion. A curation that is updated will change its associated suggestions to the rejected status.

See Update suggestions for an engine for more details.

Path parameters

edit
enterprise-search-base-url (required)

The Enterprise Search base URL for your deployment.

engine (required)

The engine name.

curation_id (required)

The identifier of the curation to update.

Request body

edit
queries (optional)

Array of queries for which the curation modifies results. This parameter can be omitted in case queries are not to be modified for the curation.

promoted (optional)

Array of document identifiers that the curation queries will return as top results. The document identifiers are ordered according to the order in which they will be presented in results. In case it is an empty array or not specified, top results for the queries will not be modified by the curation.

For meta engines, see Document IDs for meta engines

hidden (optional)

Array of document identifiers that the curation will never return as results for the specified queries. In case it is an empty array or not specified, no result for the queries will be hidden by the curation.

For meta engines, see Document IDs for meta engines

Response body

edit
id

Identifier for the updated curation.

Examples

edit

Update a curation for an engine with queries and promoted documents. As no hidden documents have been specified, the update will remove any hidden documents from the curation:

curl -X PUT '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/curations/6193db496c801b95a3cf46e3' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-H 'Content-Type: application/json' \
-d '{
    "queries": [
        "park", "garden"
    ],
    "promoted": [
        "park_olympic",
        "park_katmai"
    ]
}'

Response:

{
    "id": "cur-6193db496c801b95a3cf46e3"
}

Delete a curation

edit

Deletes a curation for an engine.

DELETE <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/<engine>/curations/<curation_id>

Path parameters

edit
enterprise-search-base-url (required)

The Enterprise Search base URL for your deployment.

engine (required)

The engine name.

curation_id (required)

The identifier of the curation to delete.

Response body

edit
deleted

Field with value true when curation is deleted.

Examples

edit

Delete a curation for an engine with a specific identifier:

curl -X DELETE '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/curations/6193db496c801b95a3cf46e3' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8'

Response:

{
  "deleted": https://xxx[true]
}

Document IDs for meta engines

edit

When specifying documents for a curation on a meta engine, you must scope each document ID to its source engine.

Use the following format: <source_engine_name>|<document_id>.

For example:

"promoted": [
  "eastern-national-parks|park_shenandoah",
  "western-national-parks|park_yosemite"
]
« Credentials API Documents API »