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 ingest 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 ingestion fundamentals, we have a helpful conceptual guide.
Schema Documents are ingested, then indexed. 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/rent-a-car/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/rent-a-car/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/rent-a-car/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/rent-a-car/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/rent-a-car/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/rent-a-car/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/rent-a-car/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/rent-a-car/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/rent-a-car/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/rent-a-car/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/rent-a-car/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/rent-a-car/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": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... Truncated!
  ]
}

Example - Same response!
No Java example available, showing cURL
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... Truncated!
  ]
}

Example - Same response!
No Node example available, showing cURL
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... Truncated!
  ]
}

Example - Same response!
No Ruby example available, showing cURL
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... Truncated!
  ]
}

Example - Same response!
No Python example available, showing cURL
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... Truncated!
  ]
}

Example - Same response!
No Javascript example available, showing cURL
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... Truncated!
  ]
}

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"
  ]
}