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
Swiftype Documentation / api: Platform API

Swiftype Platform API

This Swiftype Platform API allows you to create and control Swiftype accounts on behalf of your own users. For example, a blogging platform may wish to create a Swiftype-powered search engine for each blog on their platform, while allowing each blog's owner to have access to their own Swiftype Dashboard in order to manage their search engine (view Analytics, customize search results, etc.). With this API you can create an account for the user, create and update a search engine for them (e.g. as they create or delete blog posts), and then pass them into the Swiftype Dashboard via an authenticated link any time they wish to access their Swiftype account.

You should think of the Swiftype Platform API like a simple OAuth application. When you create a User via this API, it is as if that User had created a Swiftype account of their own, and then granted your Application access to their account. This API just short circuits that process -- creating the user and granting your Application access to their account in a single call.

Registering a Swiftype Platform Application

The very first step is to register your service as a Swiftype Platform Application. Once your Application is created you will receive a Client ID and Client Secret with which to authenticate your API requests. For now, the only way to register a Swiftype Platform Application is to email platform@swiftype.com, which we will respond to promptly.

Platform Overview

Using the Swiftype Platform is a simple, two-stage process.

  1. First, you make an API call to create a User. This call returns the new User's ID, as well as an AccessToken. You'll use this AccessToken to make API calls on behalf of the newly created user.

  2. Next, you make the usual Search API calls, but on behalf of the newly-created User. For example, to create an Engine under this User's account, you make the usual Create Engine API call, but instead of passing your own AuthToken to authenticate the request, you pass the AccessToken associated with that User's account. This tells our API to create the Engine under that User's account instead of your own. This same technique applies to all the other API calls documented in our API Documentation

Step 1: Create a User

This call creates a fully-functional Swiftype User and returns the User's Swiftype ID as well as an AccessToken that allows you to make calls on behalf of that User. You should only need to store the AccessToken in your own database (store it alongside that User's ID in your own system).

Example - Create a User using your Client ID and Client Secret.
curl -X POST 'https://api.swiftype.com/api/v1/users.json' \
  -H 'Content-Type: application/json' \
  -d  '{
        "auth_token": "j48v96cYcgsfWnsZQxrE",
        "client_id": "[CLIENT_ID]",
        "client_secret": "[CLIENT_SECRET]"
      }'
  

Example Response

{
  "id":"516c80ae1a28ad95c9000016",
  "access_token":"8694260c536e0794ecc4c26df11b175a05f15caf465f1329f37614297e10986c"
}

Step 2: Create an Engine for the User

This call creates an Engine in the User's account. Remember, this request is authenticated with the User's AccessToken, not your own API key. Be sure to keep track of the "slug" and "key" values from the response. See the Engines documentation for more details.

Example - Create an Engine named "My Blog" for a User.
curl -X POST 'https://api.swiftype.com/api/v1/engines.json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS_TOKEN_FROM_STEP_1' \
  -d '{
       "engine": {"name": "My Blog"}
     }'
  

Example Response

{
  "name":"My Blog",
  "slug":"my-blog",
  "key":"9tQsAhzSqKa3KUDmSkq5",
  "id":"516cb5c5317dfd703100000b",
  "updated_at":"2013-04-16T02:21:57Z",
  "document_count":0
}

Step 3: Create a DocumentType in the Engine

Before adding Documents to the Engine you have to create a DocumentType for them. This call creates a DocumentType named "posts" in the Engine created in the previous step. See the DocumentTypes documentation for more details.

Example - Create a DocumentType named posts in the Engine.
curl -X POST 'https://api.swiftype.com/api/v1/engines/my-blog/document_types.json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS_TOKEN_FROM_STEP_1' \
  -d '{
       "document_type": {"name": "posts"}
     }'
  

Example Response

{
  "id":"516cdff1317dfdc2d0000001",
  "name":"posts",
  "slug":"posts",
  "engine_id":"516cb5c5317dfd703100000b",
  "updated_at":"2013-04-16T05:21:53Z",
  "document_count":0,
  "field_mapping":{}
}

Step 4: Add a Document to the Engine

This call creates a Document, which gets indexed and is searchable in the search engine. See the Documents documentation for more details.

Example - Add a Document to the posts DocumentType
curl -X POST 'https://api.swiftype.com/api/v1/engines/my-blog/document_types/posts/documents.json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS_TOKEN_FROM_STEP_1' \
  -d '{
       "document": {
         "external_id": "1",
         "fields": [
           {"name": "title", "value": "My First Blog Post", "type": "string"},
           {"name": "content", "value": "Hello World! This is my first blog post.", "type": "text"}
         ]
       }
     }'
  

Example Response

{
  "external_id":"1",
  "engine_id":"516cb5c5317dfd703100000b",
  "document_type_id":"516cdff1317dfdc2d0000001",
  "id":"516ce04e317dfdc2d0000003",
  "updated_at":"2013-04-16T05:23:26Z",
  "title":"My First Blog Post",
  "content":"Hello World! This is my first blog post."
}

Finally, you can search this engine! While it's possible to authenticate as the User and search the engine via the private Search API endpoints, it's way easier to use our jQuery Autocomplete and jQuery Search plugins to handle the user-facing aspects of searching.

To install the front-end search functionality, just include jQuery, both plugin files, and use the example JavaScript shown below.

Example - Add search functionality to your website!
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
<script type='text/javascript' src='jquery.ba-hashchange.min.js'></script>
<script type="text/javascript" src="jquery.swiftype.autocomplete.js"></script>
<script type='text/javascript' src='jquery.swiftype.search.js'></script>
...
<form>
  <input type="text" id="st-search-input" class="st-search-input" />
</form>
<div id="st-results-container"></div>
...
<script type='text/javascript'>
  $(function() {
    // this adds an autocomplete to the #st-search-input
    $('#st-search-input').swiftype({
      engineKey: '[ENGINE_KEY_FROM_STEP_2]'
    });

    // this adds search functionality to the #st-search-input (accepts keyboard enter event, etc.)
    // results are rendered in the element specified in resultContainingElement.
    $('#st-search-input').swiftypeSearch({
      resultContainingElement: '#st-results-container',
      engineKey: '[ENGINE_KEY_FROM_STEP_2]'
    });
  });
</script>
  

The front-end experience is fully customizable. The Github repos contain customization instructions, and we have a tutorial describing search customizations as well.

Step 6: Let your users access the Swiftype Dashboard

You may want to allow your users to access the Swiftype Dashboard so they can manage the search engines your application has created for them. To log users into the Swiftype, you must construct a Single Sign On (SSO) URL for the user to click on.

The URL for single sign on is https://swiftype.com/sso (note that this URL should always be accessed via HTTPS) and must contain the following parameters:

  • user_id: the User ID we sent to you in Step 1.
  • client_id: the public client ID from your registered Swiftype Application.
  • timestamp: the current time in seconds since the epoch (e.g., Time.now.to_i in Ruby).
  • token: a token encoding the user ID, your application secret, and the timestamp (see below)

The token is computed like this (where secret is your Swiftype Application's client secret):

token = sha1( user_id + ":" + secret + ":" + timestamp )

When Swiftype receives the Single Sign On request, we will look up your Application based on the client_id and re-calculate the token. If the token matches, the timestamp is less than 5 minutes old, and the user has been authorized through your application, the user will be logged in. If there are any errors validating the token, the user will see an error page asking them to go back and try again.

Example - Calculating Single Sign On Link in Ruby
require 'digest/sha1'

base_url = 'https://swiftype.com/sso'
user_id = '5064a7de2ed960e715000276'
client_id = '3e4fd842fc99aecb4dc50e5b88a186c1e206ddd516cdd336da3622c4afd7e2e9'
client_secret = '4441879b5e2a9c3271f5b1a4bc223b715f091e5ed20fe75d1352e1290c7a6dfb'
timestamp = Time.now.to_i # 1379382520 in this example
token = Digest::SHA1.hexdigest("#{user_id}:#{client_secret}:#{timestamp}")

url = "#{base_url}?user_id=#{user_id}&client_id=#{client_id}&timestamp=#{timestamp}&token=#{token}"
# => => "https://swiftype.com/sso?user_id=5064a7de2ed960e715000276&client_id=3e4fd842fc99aecb4dc50e5b88a186c1e206ddd516cdd336da3622c4afd7e2e9&timestamp=1379382520&token=81033d182ad51f231cc9cda9fb24f2298a411437"
  

In order for the timestamp not to get stale, you may want to redirect users through your server or set it via JavaScript with an onclick handler. However, it is very important not to expose your client secret. The token must only be generated on your server.