Curations API referenceedit

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.

Accessedit

To access curations API operations, you’ll need:

  • The name of your engine: <engine>
  • A private API key: <key>
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/<engine>/curations' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <key>'

List all curations for an engineedit

Return all curations for a given engine.

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

Path parametersedit

engine (required)

The engine name.

Query parametersedit

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, which is also the maximum page size value.

Request bodyedit

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 bodyedit

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

Examplesedit

Request all curations for an engine:

curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.ioapi/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 curationedit

Retrieves information for a specific curation.

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

Path parametersedit

engine (required)

The engine name.

curation_id (required)

The curation identifier.

Response bodyedit

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

Examplesedit

Request a single curation for an engine:

curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.ioapi/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 curationedit

Creates a new curation for one or more queries.

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

Path parametersedit

engine (required)

The engine name.

Request bodyedit

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 bodyedit

id

Identifier for the newly created curation.

Examplesedit

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

curl -X POST 'https://[instance id].ent-search.[region].[provider].cloud.es.ioapi/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 curationedit

Updates a curation for an engine.

PUT 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 parametersedit

engine (required)

The engine name.

curation_id (required)

The identifier of the curation to update.

Request bodyedit

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 bodyedit

id

Identifier for the updated curation.

Examplesedit

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 'https://[instance id].ent-search.[region].[provider].cloud.es.ioapi/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 curationedit

Deletes a curation for an engine.

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

Path parametersedit

engine (required)

The engine name.

curation_id (required)

The identifier of the curation to delete.

Response bodyedit

deleted

Field with value true when curation is deleted.

Examplesedit

Delete a curation for an engine with a specific identifier:

curl -X DELETE 'https://[instance id].ent-search.[region].[provider].cloud.es.ioapi/as/v1/engines/national-parks-demo/curations/6193db496c801b95a3cf46e3' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8'

Response:

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

Document IDs for meta enginesedit

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"
]