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
Site Search Documentation / api: API Overview

API Overview

The Swiftype Search API is a powerful full-text search API that gives you full programatic control over the content in your search engine, while still allowing you to use the Swiftype Dashboard for controlling your search engine's behavior. The Search API should be employed by users who wish to bypass the Web Crawling aspect of engine creation and updating. With the Search API you create your search engine on your own terms, using a schema you define for your own data, and which you can update as often as you like.


There are 3 primary resources in the Swiftype API: Engine, DocumentType, and Document.


Engines are the top-level objects in your search index. They have a free-form name field that we translate into a slug identifier, which is used as the ENGINE_ID to reference the engine in all API calls.


DocumentTypes specify the structure of a set of documents in the Engine and are the entry point for searches. There are multiple types of fields on a DocumentType — string, text, enum, integer, float, date, and location.


Documents represent all of the pieces of content in an Engine. They are children of a DocumentType and conform to its field specification (note: you do not need to specify the fields ahead of time, they will be inferred by the contents of a document).

When you perform a search on a DocumentType, you will receive Document results. external_id is the only required field for a Document. It can be any value, for example: the numeric ID you use to identify the object in your own data store.


You may authenticate requests to the API using the following method:

Method Description
HTTP Basic Auth Use your auth_token as the username. Do not include a password.
Authentication Token Add the auth_token parameter to each request. Your auth_token is your account's API key.

Parameter Encoding

All API endpoints accept parameters as a JSON-encoded request body. This is the recommended method and is shown in the examples in this documentation.

You can also submit parameters using form encoding, but nested parameters must be named according to Ruby on Rails conventions.

For example, the JSON parameter {"filters": {"videos": {"status": ["draft", "published"]}}} is equivalent to filters[videos][status][]=draft&filters[videos][status][]=published

Document Field Types

Documents in your search engine may contain as many fields as you like. To decide which field types to use, consider the tables below and read the Swiftype schema design tutorial

Field Types

Option Description
string Smaller pieces of text, such as a book title. These are used for autocomplete and full-text search. String fields can also be used for filtering, faceting, and sorting
text Large bodies of text, such as a book chapter. These are only used for full-text search.
enum String attributes of a document that should be used for exact comparisons, such as a URL or the genre of a book. Enum fields can be used for filtering, faceting, and sorting. Exact matches will be included in results of autocomplete and full-text search.
integer An integer value, such as the number of sales of a book (e.g. 1234).
float A floating point value, such as the price of a book (e.g. 3.99).
date ISO 8601 compatible time strings, such as the publication date of a book.
location A geographic location specified by latitude and longitude (e.g. lat: 53.2, lon: 27.6).

Field Type Use Cases

Type Search Optimized for Autocomplete Functional Boosts Filtering Sorting Facets
string Yes Yes No Yes Yes Yes
text Yes No No No No No
enum Yes No No Yes Yes Yes
integer Yes No Yes Yes Yes Yes
float Yes No Yes Yes Yes Yes
date No No No Yes Yes Yes
location No No No Yes No No

Field Specification Examples

Type Name Value JSON
string title "My Post Title" {"type":"string","name":"title","value":"My Post Title"}
text body "This is the long content of my post..." {"type":"text","name":"body","value":"This is the long content of my post..."}
enum public true {"type":"enum","name":"public","value":true}
integer views 387 {"type":"integer","name":"views","value":387}
float price 6.95 {"type":"float","name":"price","value":6.95}
date posted_at "2012-07-02T20:44:05-07:00" {"type":"date","name":"posted_at","value":"2012-07-02T20:44:05-07:00"}
location posted_from {"lat":56.2,"lon":44.7} {"type":"location","name":"posted_from","value":{"lat":56.2,"lon":44.7}}

Array values

When creating a document, pass the values as an array.

{"type": "enum", "name": "tags", "value": ["tag1", "tag2", "tag3"]}

Naming fields

Document field names must be limited to alphanumeric ASCII characters. Whitespace, special characters, and non-ASCII encoding are not allowed.

Engine Slugs

When you name an engine we will assign your engine a slug based on the engine name. For example, an engine named "Bookstore Search Engine" would get the slug "bookstore-search-engine". You will use the slug as the engine_id to reference a particular engine when sending requests to the api.