search mobile facets autocomplete spellcheck crawler rankings weights synonyms analytics engage api customize documentation install setup technology content domains user history info home business cart chart contact email activate analyticsalt analytics autocomplete cart contact content crawling custom documentation domains email engage faceted history info install mobile person querybuilder search setup spellcheck synonyms weights engage_search_term engage_related_content engage_next_results engage_personalized_results engage_recent_results success add arrow-down arrow-left arrow-right arrow-up caret-down caret-left caret-right caret-up check close content conversions-small conversions details edit grid help small-info error live magento minus move photo pin plus preview refresh search settings small-home stat subtract text trash unpin wordpress x alert case_deflection advanced-permissions keyword-detection predictive-ai sso

Engines

Engines allow you to index documents and perform various search functions. Once indexed, database or backend API objects become documents that coincide with your Engine schema. You may have multiple Engines per account - this endpoint will help you manage your various Engines.

Be sure to familiarize yourself with multi-language support before creating a new Engine!

The API allows you to...

Authentication

For authentication, the Credentials endpoint requires your unique Host Identifier, the name of your Engine and a Private API Key. The key begins with private- and was created for you upon account creation. You can find it, along with your Host Identifier, within the Credentials menu.

They fit into your requests like so:

curl -X GET 'https://[HOST_IDENTIFIER].api.swiftype.com/api/as/v1/engines/[ENGINE]/engines' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer [PRIVATE_API_KEY]'

Multi-Language Support

Each Engine can be given a language. The default language setting is Universal. It is well optimized for general or multi-language use cases. The Universal language type will return null. The other languages will return their respective Language Code. The codes adhere to a subset of the IETF RFC 5646, which coincide with ISO 639-1 and ISO 3166-1.

LanguageLanguage 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
"Koreanko
“Portuguese"pt
“Russian"ru
“Spanish"es
“Thai"th
"Universal"null

Retrieve an Engine

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

GET /api/as/v1/engines/{ENGINE_NAME}
Example
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
{
  "name": "national-parks-demo",
  "language": "en"
}

Example
Client client = new Client("host-2376rb", "private-xxxxxxxxxxxxxxxxxxxx");

String engineName = "national-parks-demo";

client.getEngine(engineName);

Example Response
Map<String, Object>: {
  "name": "national-parks-demo",
  "language": "en"
}

Example
const client = new SwiftypeAppSearchClient('host-2376rb', 'private-xxxxxxxxxxxxxxxxxxxx')

const engineName = 'national-parks-demo'

client.getEngine(engineName)

Example Response
{
  "name": "national-parks-demo",
  "language": "en"
}

Example
host_identifier = 'host-2376rb'
api_key = 'private-xxxxxxxxxxxxxxxxxxxx'
client = SwiftypeAppSearch::Client.new(host_identifier: host_identifier, api_key: api_key)

engine_name = 'national-parks-demo'

puts client.get_engine(engine_name)

Example Response
{
  'name' => 'national-parks-demo',
  'language' => 'en'
}

Example
host_identifier = 'host-2376rb'
api_key = 'private-xxxxxxxxxxxxxxxxxxxx'
client = Client(host_identifier, api_key)

engine_name = 'national-parks-demo'

client.get_engine(engine_name)

Example Response
{
    'name': 'national-parks-demo',
    'language': 'en'
}

Example
No Javascript example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Javascript example available, showing cURL
{
  "name": "national-parks-demo",
  "language": "en"
}

List Engines

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

GET /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

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 'https://host-2376rb.api.swiftype.com/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",
      "language": null
    }
  ]
}

Example - A JSON body containing the current and size parameters. Expects the first page of results, with 20 documents per result.
Client client = new Client("host-2376rb", "private-xxxxxxxxxxxxxxxxxxxx");

client.listEngines();

Example Response
List<Map<String, Object>>: [
  { "name": "national-parks-demo", "language": null }
]

Example - A JSON body containing the current and size parameters. Expects the first page of results, with 20 documents per result.
const client = new SwiftypeAppSearchClient('host-2376rb', 'private-xxxxxxxxxxxxxxxxxxxx')

const options = { page: { current: 1, size: 20 } }

client.listEngines(options)

Example Response
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 1,
      "size": 20
    }
  },
  "results": [
    {
      "name": "national-parks-demo",
      "language": null
    }
  ]
}

Example - A JSON body containing the current and size parameters. Expects the first page of results, with 20 documents per result.
host_identifier = 'host-2376rb'
api_key = 'private-xxxxxxxxxxxxxxxxxxxx'
client = SwiftypeAppSearch::Client.new(host_identifier: host_identifier, api_key: api_key)

puts client.list_engines

Example Response
{
  'meta' => {
    'page' => {
      'current' => 1,
      'total_pages' => 1,
      'total_results' => 1,
      'size' => 20
    }
  },
  'results' => [
    {
      'name' => 'national-parks-demo',
      'language' => nil
    }
  ]
}

Example - A JSON body containing the current and size parameters. Expects the first page of results, with 20 documents per result.
host_identifier = 'host-2376rb'
api_key = 'private-xxxxxxxxxxxxxxxxxxxx'
client = Client(host_identifier, api_key)

client.list_engines(current=1, size=20)

Example Response
{
    'meta': {
        'page': {
            'current': 1,
            'total_pages': 1,
            'total_results': 1,
            'size': 20
        }
    },
    'results': [
        {
            'name': 'national-parks-demo',
            'language': null
        }
    ]
}

Example - A JSON body containing the current and size parameters. Expects the first page of results, with 20 documents per result.
No Javascript example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": "1",
    "size": "20"
  }
}'
Example Response
No Javascript example available, showing cURL
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 1,
      "size": 20
    }
  },
  "results": [
    {
      "name": "national-parks-demo",
      "language": null
    }
  ]
}

Query Parameters

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 'https://host-2376rb.api.swiftype.com/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",
      "language": null
    }
  ]
}

Example - A parameterized query containing the current and size parameters. Expects the first page of results, with 20 documents per result.
No Java example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines?page[size]=20&page[current]=1' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Java example available, showing cURL
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 1,
      "size": 20
    }
  },
  "results": [
    {
      "name": "national-parks-demo",
      "language": null
    }
  ]
}

Example - A parameterized query containing the current and size parameters. Expects the first page of results, with 20 documents per result.
No Node example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines?page[size]=20&page[current]=1' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Node example available, showing cURL
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 1,
      "size": 20
    }
  },
  "results": [
    {
      "name": "national-parks-demo",
      "language": null
    }
  ]
}

Example - A parameterized query containing the current and size parameters. Expects the first page of results, with 20 documents per result.
No Ruby example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines?page[size]=20&page[current]=1' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Ruby example available, showing cURL
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 1,
      "size": 20
    }
  },
  "results": [
    {
      "name": "national-parks-demo",
      "language": null
    }
  ]
}

Example - A parameterized query containing the current and size parameters. Expects the first page of results, with 20 documents per result.
No Python example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines?page[size]=20&page[current]=1' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Python example available, showing cURL
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 1,
      "size": 20
    }
  },
  "results": [
    {
      "name": "national-parks-demo",
      "language": null
    }
  ]
}

Example - A parameterized query containing the current and size parameters. Expects the first page of results, with 20 documents per result.
No Javascript example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines?page[size]=20&page[current]=1' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Javascript example available, showing cURL
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 1,
      "size": 20
    }
  },
  "results": [
    {
      "name": "national-parks-demo",
      "language": null
    }
  ]
}

Create an Engine

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

POST /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 multi-language support.
Example
curl -X POST 'https://host-2376rb.api.swiftype.com/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",
  "language": null
}

Example
Client client = new Client("host-2376rb", "private-xxxxxxxxxxxxxxxxxxxx");

String engineName = "national-parks-demo";

client.createEngine(engineName);

Example Response
Map<String, Object>: {
  "name": "national-parks-demo",
  "language": null
}

Example
const client = new SwiftypeAppSearchClient('host-2376rb', 'private-xxxxxxxxxxxxxxxxxxxx')

const engineName = 'national-parks-demo'

client.createEngine(engineName)

Example Response
{
  "name": "national-parks-demo",
  "language": null
}

Example
host_identifier = 'host-2376rb'
api_key = 'private-xxxxxxxxxxxxxxxxxxxx'
client = SwiftypeAppSearch::Client.new(host_identifier: host_identifier, api_key: api_key)

engine_name = 'national-parks-demo'

puts client.create_engine(engine_name)

Example Response
{
  'name' => 'national-parks-demo',
  'language' => nil
}

Example
host_identifier = 'host-2376rb'
api_key = 'private-xxxxxxxxxxxxxxxxxxxx'
client = Client(host_identifier, api_key)

engine_name = 'national-parks-demo'

client.create_engine(engine_name)

Example Response
{
    'name': 'national-parks-demo',
    'language': null
}

Example
No Javascript example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "name": "national-parks-demo"
}'
Example Response
No Javascript example available, showing cURL
{
  "name": "national-parks-demo",
  "language": null
}

Delete an Engine

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

DELETE /api/as/v1/engines/{ENGINE_NAME}
Example
curl -X DELETE 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
{
  "deleted": true
}

Example
Client client = new Client("host-2376rb", "private-xxxxxxxxxxxxxxxxxxxx");

String engineName = "national-parks-demo";

client.destroyEngine(engineName);

Example Response
Map<String, Boolean>: {
  "deleted": true
}

Example
const client = new SwiftypeAppSearchClient('host-2376rb', 'private-xxxxxxxxxxxxxxxxxxxx')

const engineName = 'national-parks-demo'

client.destroyEngine(engineName)

Example Response
{
  "deleted": true
}

Example
host_identifier = 'host-2376rb'
api_key = 'private-xxxxxxxxxxxxxxxxxxxx'
client = SwiftypeAppSearch::Client.new(host_identifier: host_identifier, api_key: api_key)

engine_name = 'national-parks-demo'

puts client.destroy_engine(engine_name)

Example Response
{
  'deleted' => true
}

Example
host_identifier = 'host-2376rb'
api_key = 'private-xxxxxxxxxxxxxxxxxxxx'
client = Client(host_identifier, api_key)

engine_name = 'national-parks-demo'

client.destroy_engine(engine_name)

Example Response
{
    'deleted': True
}

Example
No Javascript example available, showing cURL
curl -X DELETE 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Javascript example available, showing cURL
{
  "deleted": true
}

Errors

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.

What's Next?

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.


Stuck? Looking for help? Contact Support!