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

› ›

Engines API

edit

Engines API

edit

Engines can be language optimized. Read the Language Optimization guide.

Engines index documents and perform various search functions.

You may have multiple Engines per account - this endpoint will help you manage your various Engines.

Authentication

edit

For authentication, the Engines endpoint requires...

The name of your Engine: [ENGINE]
A Private API Key: [PRIVATE_API_KEY]

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer [PRIVATE_API_KEY]'

Retrieve an Engine

edit

Retrieves an Engine by name. Returns a JSON object containing a name, type and language property.

GET <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/{ENGINE_NAME}

Example

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

Example Response

{
  "name": "national-parks-demo",
  "type": "default",
  "language": "en",
  "document_count": 12
}

List Engines

edit

Retrieves all Engines that the API Key is scoped to access.

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

page (optional): JSON object containing current and size, where current is the current page number and size is the page size. The maximum for size is 25, and be will truncated if a larger size is requested. The default is the first page of engines with pagination at 25.

You have two options as to how you might send in your parameters:

JSON Object

edit

A JSON object...

Example - A JSON body containing the current and size parameters. Expects the first page of results, with 20 documents per result.

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": "1",
    "size": "20"
  }
}'

Example Response

{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 1,
      "size": 20
    }
  },
  "results": [
    {
      "name": "national-parks-demo",
      "type": "default",
      "language": null,
      "document_count": 12
    }
  ]
}

Query Parameters

edit

Rails-style query parameters:

Example - A parameterized query containing the current and size parameters. Expects the first page of results, with 20 documents per result.

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines?page[size]=20&page[current]=1' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Example Response

{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 1,
      "size": 20
    }
  },
  "results": [
    {
      "name": "national-parks-demo",
      "type": "default",
      "language": null,
      "document_count": 12
    }
  ]
}

Create an Engine

edit

Creates a new Engine object. Returns a JSON object with a name, type and language property.

Reserved names include: new, collection, create_engine, and engine_limit.

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

name (required)

Name of the Engine. Can only contain lowercase letters, numbers, and hyphens.

language (optional)

The language associated with a given Engine. Will default to Universal, which will return null. To specify a language, see the list of supported languages.

index_create_settings_override (optional)

A dictionary of settings that will override the default index settings.

Currently, the only index setting you can override is number_of_shards. See example.

You cannot use index_create_settings_override when creating a meta-engine.

Example - Creating an Engine with the default Universal language.

curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "name": "national-parks-demo"
}'

Example Response

{
  "name": "national-parks-demo",
  "type": "default",
  "language": null,
  "document_count": 0
}

Example - Creating an Engine with the Korean language.

curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "name": "national-parks-demo",
  "language": "ko"
}'

Example Response

{
  "name": "korean-example",
  "type": "default",
  "language": "ko",
  "document_count": 0
}

Example - Creating an Engine with 10 shards.

curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "name": "my-large-engine",
  "index_create_settings_override": {
    "number_of_shards": 10
  }
}'

Example Response

{
  "name":"my-large-engine",
  "type":"default",
  "language":null,
  "index_create_settings_override": {
    "number_of_shards": 10
  },
  "document_count": 0
}

Delete an Engine

edit

Delete an Engine by name. Returns a JSON object with a deleted property denoting whether the engine was successfully deleted.

DELETE <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/{ENGINE_NAME}

Example

curl -X DELETE '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Example Response

{
  "deleted": true
}

Supported Languages

edit

Engines can be optimized for the following languages:

Language	Language Code, ISO 639-1 and ISO 3166-1.
"Brazilian Portuguese"	`pt-br`
"Chinese"	`zh`
"Danish""	`da`
"Dutch"	`nl`
"English"	`en`
"French"	`fr`
"German"	`de`
"Italian"	`it`
"Japanese"	`ja`
"Korean	`ko`
"Portuguese"	`pt`
"Russian"	`ru`
"Spanish"	`es`
"Thai"	`th`
"Universal"	`null`

Errors

edit

The endpoint will return an error if:

The API Key does not have read permissions for the requested Engine.
The requested Engine does not exist.
The Engine object is not well formed.
The API Key does not have permissions to create an Engine.
The Engine already exists and so cannot be created.
The Engine can’t be created because the shard limit is reached in Elasticsearch.

What’s Next?

edit

An Engine is the beating heart of the search experience. Now you may want to learn more about how you can add, destroy and update, the Documents - the life-blood - within them. If you want a deep look into how users are interacting with your engines, then the Analytics and Clickthrough endpoints are worth discovering.

« Documents API Log settings API »