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

Overview, API References

There are countless ways to write dynamic code against a set of robust APIs. App Search provides you with a variety of useful endpoints to help you craft intuitive, relevant and useful search experiences.

In most cases, you will be interfacing with the many endpoints through one of our first-party App Search clients.

The following endpoints are well-documented, fully supported, and available for you:

Endpoint
Credentials Your Engine needs a Key! By leveraging a special Private Admin Key, you may view, add, remove or re-scope Public Search Keys, Private Admin Keys and Private Admin Keys.
Engines You have full control over your Search Engines, or Engine for short. You may view, create and delete your Engines.
Documents If you are looking to index documents into your Engine, you can POST them to this endpoint. You are also able to view, update and delete documents. To further explain core indexing fundamentals, we have a helpful conceptual guide.
Schema The indexing structure is defined through your schema. You can view your schema or update field types.
Search Each time a search is completed, a search query has been made against your Engine. There are many useful ways to build search queries. We have a handy conceptual guide to help you gain a deeper understanding of Search, too.
Synonyms Fast, quick, swift, rapid! Often times there is more than one way to describe an item. Synonyms allow you to group similar terms together so that you can improve query relevance.
Curations A Curation is a tool to help you arrange your result data. You may hide or promote specific search results, to persuade or dissuade an interaction.
Analytics The Analytics endpoint is a powerful and flexible way to examine the queries that are performed against your Engine. You can gain deep insight into which results are receiving engagement.
Clickthrough Often, a click is the accomplishment of a business goal. You can see the query that came before the click, which document received the click and more. This is a useful tool for analysis!
Logs Every Engine-level request against App Search will appear within the Log - including requests to the API Log. You have full transparency into what is happening.


However you choose to wield these APIs, it will be valuable to first explore...

Happy Coding!

Parameter Encoding

All App Search endpoints accept parameters as a JSON-encoded request body. This is the recommended method and the one you will see in all of our examples. However, you can also submit query parameters using form encoding. Nested parameters must be named according to Ruby on Rails conventions.

For example:

Example - JSON request body
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'

Example - JSON request body
No Java example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'

Example - JSON request body
No Node example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'

Example - JSON request body
No Ruby example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'

Example - JSON request body
No Python example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'

Example - JSON request body
No Javascript example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'

... compared with:

Example - Rails-style query parameters
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Example - Rails-style query parameters
No Java example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Example - Rails-style query parameters
No Node example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Example - Rails-style query parameters
No Ruby example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Example - Rails-style query parameters
No Python example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Example - Rails-style query parameters
No Javascript example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Both options will return the same response, which is the second page of results with 15 pages per result:

Example - Same response!
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
       "nps_link": {
         "raw": "https://www.nps.gov/wrst/index.htm"
       },
       "title": {
         "raw": "Wrangell–St. Elias"
       },
       "date_established": {
         "raw": "1980-12-02T06:00:00+00:00"
       },
       "world_heritage_site": {
         "raw": "true"
       },
       "states": {
         "raw": [
           "Alaska"
         ]
       },
       "description": {
         "raw": "An over 8 million acres (32,375 km2) plot of mountainous country—the largest National Park in the system—protects the convergence of the Alaska, Chugach, and Wrangell-Saint Elias Ranges, which include many of the continent's tallest mountains and volcanoes, including the 18,008-foot Mount Saint Elias. More than a quarter of the park is covered with glaciers, including the tidewater Hubbard Glacier, piedmont Malaspina Glacier, and valley Nabesna Glacier."
       },
       "visitors": {
         "raw": 79047
       },
       "id": {
         "raw": "park_wrangell–st.-elias"
       },
       "location": {
         "raw": "61,-142"
       },
       "square_km": {
         "raw": 33682.6
       },
       "acres": {
         "raw": 8323146.48
       },
       "_meta": {
         "score": 0.00437395
       }
    },
    # ... Truncated!
  ]
}

Example - Same response!
No Java example available, showing cURL
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
       "nps_link": {
         "raw": "https://www.nps.gov/wrst/index.htm"
       },
       "title": {
         "raw": "Wrangell–St. Elias"
       },
       "date_established": {
         "raw": "1980-12-02T06:00:00+00:00"
       },
       "world_heritage_site": {
         "raw": "true"
       },
       "states": {
         "raw": [
           "Alaska"
         ]
       },
       "description": {
         "raw": "An over 8 million acres (32,375 km2) plot of mountainous country—the largest National Park in the system—protects the convergence of the Alaska, Chugach, and Wrangell-Saint Elias Ranges, which include many of the continent's tallest mountains and volcanoes, including the 18,008-foot Mount Saint Elias. More than a quarter of the park is covered with glaciers, including the tidewater Hubbard Glacier, piedmont Malaspina Glacier, and valley Nabesna Glacier."
       },
       "visitors": {
         "raw": 79047
       },
       "id": {
         "raw": "park_wrangell–st.-elias"
       },
       "location": {
         "raw": "61,-142"
       },
       "square_km": {
         "raw": 33682.6
       },
       "acres": {
         "raw": 8323146.48
       },
       "_meta": {
         "score": 0.00437395
       }
    },
    # ... Truncated!
  ]
}

Example - Same response!
No Node example available, showing cURL
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
       "nps_link": {
         "raw": "https://www.nps.gov/wrst/index.htm"
       },
       "title": {
         "raw": "Wrangell–St. Elias"
       },
       "date_established": {
         "raw": "1980-12-02T06:00:00+00:00"
       },
       "world_heritage_site": {
         "raw": "true"
       },
       "states": {
         "raw": [
           "Alaska"
         ]
       },
       "description": {
         "raw": "An over 8 million acres (32,375 km2) plot of mountainous country—the largest National Park in the system—protects the convergence of the Alaska, Chugach, and Wrangell-Saint Elias Ranges, which include many of the continent's tallest mountains and volcanoes, including the 18,008-foot Mount Saint Elias. More than a quarter of the park is covered with glaciers, including the tidewater Hubbard Glacier, piedmont Malaspina Glacier, and valley Nabesna Glacier."
       },
       "visitors": {
         "raw": 79047
       },
       "id": {
         "raw": "park_wrangell–st.-elias"
       },
       "location": {
         "raw": "61,-142"
       },
       "square_km": {
         "raw": 33682.6
       },
       "acres": {
         "raw": 8323146.48
       },
       "_meta": {
         "score": 0.00437395
       }
    },
    # ... Truncated!
  ]
}

Example - Same response!
No Ruby example available, showing cURL
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
       "nps_link": {
         "raw": "https://www.nps.gov/wrst/index.htm"
       },
       "title": {
         "raw": "Wrangell–St. Elias"
       },
       "date_established": {
         "raw": "1980-12-02T06:00:00+00:00"
       },
       "world_heritage_site": {
         "raw": "true"
       },
       "states": {
         "raw": [
           "Alaska"
         ]
       },
       "description": {
         "raw": "An over 8 million acres (32,375 km2) plot of mountainous country—the largest National Park in the system—protects the convergence of the Alaska, Chugach, and Wrangell-Saint Elias Ranges, which include many of the continent's tallest mountains and volcanoes, including the 18,008-foot Mount Saint Elias. More than a quarter of the park is covered with glaciers, including the tidewater Hubbard Glacier, piedmont Malaspina Glacier, and valley Nabesna Glacier."
       },
       "visitors": {
         "raw": 79047
       },
       "id": {
         "raw": "park_wrangell–st.-elias"
       },
       "location": {
         "raw": "61,-142"
       },
       "square_km": {
         "raw": 33682.6
       },
       "acres": {
         "raw": 8323146.48
       },
       "_meta": {
         "score": 0.00437395
       }
    },
    # ... Truncated!
  ]
}

Example - Same response!
No Python example available, showing cURL
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
       "nps_link": {
         "raw": "https://www.nps.gov/wrst/index.htm"
       },
       "title": {
         "raw": "Wrangell–St. Elias"
       },
       "date_established": {
         "raw": "1980-12-02T06:00:00+00:00"
       },
       "world_heritage_site": {
         "raw": "true"
       },
       "states": {
         "raw": [
           "Alaska"
         ]
       },
       "description": {
         "raw": "An over 8 million acres (32,375 km2) plot of mountainous country—the largest National Park in the system—protects the convergence of the Alaska, Chugach, and Wrangell-Saint Elias Ranges, which include many of the continent's tallest mountains and volcanoes, including the 18,008-foot Mount Saint Elias. More than a quarter of the park is covered with glaciers, including the tidewater Hubbard Glacier, piedmont Malaspina Glacier, and valley Nabesna Glacier."
       },
       "visitors": {
         "raw": 79047
       },
       "id": {
         "raw": "park_wrangell–st.-elias"
       },
       "location": {
         "raw": "61,-142"
       },
       "square_km": {
         "raw": 33682.6
       },
       "acres": {
         "raw": 8323146.48
       },
       "_meta": {
         "score": 0.00437395
       }
    },
    # ... Truncated!
  ]
}

Example - Same response!
No Javascript example available, showing cURL
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
       "nps_link": {
         "raw": "https://www.nps.gov/wrst/index.htm"
       },
       "title": {
         "raw": "Wrangell–St. Elias"
       },
       "date_established": {
         "raw": "1980-12-02T06:00:00+00:00"
       },
       "world_heritage_site": {
         "raw": "true"
       },
       "states": {
         "raw": [
           "Alaska"
         ]
       },
       "description": {
         "raw": "An over 8 million acres (32,375 km2) plot of mountainous country—the largest National Park in the system—protects the convergence of the Alaska, Chugach, and Wrangell-Saint Elias Ranges, which include many of the continent's tallest mountains and volcanoes, including the 18,008-foot Mount Saint Elias. More than a quarter of the park is covered with glaciers, including the tidewater Hubbard Glacier, piedmont Malaspina Glacier, and valley Nabesna Glacier."
       },
       "visitors": {
         "raw": 79047
       },
       "id": {
         "raw": "park_wrangell–st.-elias"
       },
       "location": {
         "raw": "61,-142"
       },
       "square_km": {
         "raw": 33682.6
       },
       "acres": {
         "raw": 8323146.48
       },
       "_meta": {
         "score": 0.00437395
       }
    },
    # ... Truncated!
  ]
}

Query Syntax

When performing queries using the Search API, you may apply select Lucene Query Syntax functions.

The supported functions are: double quoted strings, + and -, AND, OR, and NOT.

Example - Performing a single query search using Lucene Query Syntax.
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "wyoming AND montana OR california NOT washington"
}'

Example - Performing a single query search using Lucene Query Syntax.
No Java example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "wyoming AND montana OR california NOT washington"
}'

Example - Performing a single query search using Lucene Query Syntax.
No Node example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "wyoming AND montana OR california NOT washington"
}'

Example - Performing a single query search using Lucene Query Syntax.
No Ruby example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "wyoming AND montana OR california NOT washington"
}'

Example - Performing a single query search using Lucene Query Syntax.
No Python example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "wyoming AND montana OR california NOT washington"
}'

Example - Performing a single query search using Lucene Query Syntax.
No Javascript example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "wyoming AND montana OR california NOT washington"
}'

Compression, gzip

The API supports gzip. Your requests to App Search may contain an Accept-Encoding header. You can use this to notify the API that you are capable of accepting and unpacking responses that are compressed via gzip.

curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/search' \
-H 'Content-Type: application/json' \
-H 'Accept-Encoding: gzip' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "everglade"
}'

Error Handling

There are three types of errors that you might run into when creating API requests:

Invalid Keys

Your choice of Key will depend on the endpoint you choose to access:

Key Name Key Prefix Endpoint
Public Search Key public- Search endpoint only.
Private API Key private- All endpoints except Credentials.
It is recommended that you use the Public Search Key when using the Search endpoint.
Private Admin Key admin- Credentials endpoint only.

If you use the incorrect key or format the key in an incorrect way, then you will receive a 400 error akin to:

{
  "error": "Invalid authentication token."
}

Decoding Error, Malformed Requests

If you happen to make a mistake with your formatting, you will receive a 400 error:

{
  "errors": [
    "There was a decoding error. Please ensure your request is valid."
  ]
}

To address this, ensure that your any JSON objects or URL parameters are formatted in the correct manner.

Endpoint Specific Errors

Each API Reference will show you how to structure your requests. If you happen to make a mistake, there are a variety of helpful errors that will inform you upon what to fix. Despite receiving a status code of 200, you will not succeed in making your request. Look for the Errors section at the end of each endpoint.

Errors might look like this:

{
  "errors": [
    "Missing required parameter: filters[date][from]"
  ]
}
{
  "errors": [
    "curation must include either promoted or hidden"
  ]
}