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

Documents

Want to start with the basics? Give our Indexing Documents guide a read.


This endpoint allows you to create, update, delete, and display documents.

There is a 100 document per request limit and each document must be less than 102,400 bytes. Errors will be present in the response body and are not always expressed by response code. See errors for more details.

Note: When indexing a document via a POST request, the document is received, then indexed. When making requests that contain many large documents you may experience a few seconds delay. Once indexing is complete, then the documents will become searchable.

With this endpoint, you can:

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]/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer [PRIVATE_API_KEY]'

Create or Update Documents

Documents are JSON objects with up to 64 key-value pairs where the key is the field name and the value is the content.

There are five key points to understand whilst creating documents:

  1. Documents are sent in via an array and are indexed or rejected independently. All valid documents in the payload will be indexed and all invalid documents will be rejected.

  2. If no id is provided, then one will be created for you - multiple documents will be created by submitting the same content multiple times without an id.

  3. Including an id that already exists will update the document instead of creating a new one.

  4. If the Engine has not seen the field before, then it will create a new field of type text. There are a number of restrictions on field names:

    • can only contain lowercase letters, numbers, and underscores
    • must contain at least one lowercase letter
    • must be a string
    • cannot contain whitespace
    • cannot have a leading underscore
    • cannot contain more than 64 characters
    • cannot be a reserved field: external_id, Engine_id, highlight, or, and, not, any, all, none
    • must be unique within individual documents
  5. An empty errors array denotes a successful index of the document.

For more information on Field Types, see the Schema API endpoint.


POST /api/as/v1/engines/{ENGINE_NAME}/documents

Example - A POST request adding three documents to the national-parks-demo Engine.
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '[
  {
     "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
     }
  }
]'
Example Response
[
  {
    "id": "park_wrangell–st.-elias",
    "errors": []
  }
]

Example - A POST request adding three documents to the national-parks-demo Engine.
Client client = new Client("host-2376rb", "private-xxxxxxxxxxxxxxxxxxxx");

String engineName = "national-parks-demo";

Map<String, Object> doc1 = new HashMap<>(); doc1.put("id", "park_zion"); doc1.put("date_established", "1919-11-19T06:00:00Z"); doc1.put("square_km", "595.8"); doc1.put("acres", "147236.02"); doc1.put("location", "37.3,-113.05"); doc1.put("world_heritage_site", "false"); doc1.put("visitors", "4295127"); doc1.put("title", "Zion"); doc1.put("states", "Utah"); doc1.put("nps_link", "https://www.nps.gov/zion/index.htm"); doc1.put("description", "Located at the junction of the Colorado Plateau, Great Basin, and Mojave Desert, this park contains sandstone features such as mesas, rock towers, and canyons, including the Virgin River Narrows. The various sandstone formations and the forks of the Virgin River create a wilderness divided into four ecosystems: desert, riparian, woodland, and coniferous forest.");

client.indexDocuments(engineName, Arrays.asList(doc1, doc2, doc3));

Example Response
List<Map<String, Object>>: [
  {
    "id": "park_zion",
    "errors": []
  }
]

Example - A POST request adding three documents to the national-parks-demo Engine.
const client = new SwiftypeAppSearchClient('host-2376rb', 'private-xxxxxxxxxxxxxxxxxxxx')

const engineName = 'national-parks-demo'

const documents = [ { "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 } } ]

client.indexDocuments(engineName, documents)

Example Response
[
  {
    "id": "park_zion",
    "errors": []
  }
]

Example - A POST request adding three documents to the national-parks-demo Engine.
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'

documents = [ { "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 } } ]

puts client.index_documents(engine_name, documents)

Example Response
[
  {
    'id' => 'park_zion',
    'errors' => []
  }
]

Example - A POST request adding three documents to the national-parks-demo Engine.
host_identifier = 'host-2376rb'
api_key = 'private-xxxxxxxxxxxxxxxxxxxx'
client = Client(host_identifier, api_key)

engine_name = 'national-parks-demo' query = 'everglade'

documents = [ { '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 } } ]

client.index_documents(engine_name, documents)

Example Response
[
    {
        'id': 'park_zion',
        'errors': []
    }
]

Example - A POST request adding three documents to the national-parks-demo Engine.
No Javascript example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '[
  {
     "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
     }
  }
]'
Example Response
No Javascript example available, showing cURL
[
  {
    "id": "park_wrangell–st.-elias",
    "errors": []
  }
]

Partial Update (PATCH)

Update specific document fields by id and field. The id is required and new fields can not be created using PATCH!

PATCH /api/as/v1/engines/{ENGINE_NAME}/documents
Example - A PATCH providing partial updates to 3 actual documents and attempting to update 3 erroneous documents.
curl -X PATCH 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '[
  { "id": "park_yosemite" },
  { "title": "Everglades" },
  { "id": "park_wind-cave", "date_established": "1903-01-09T06:00:00Z" }
]'
Example Response
[
  {
    "id": "park_yosemite",
    "errors": []
  },
  {
    "id": "",
    "errors": [
      "Missing required key 'id'"
    ]
  },
  {
    "id": "park_wind-cave",
    "errors": []
  }
]

Example - A PATCH providing partial updates to 3 actual documents and attempting to update 3 erroneous documents.
No Java example available, showing cURL
curl -X PATCH 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '[
  { "id": "park_yosemite" },
  { "title": "Everglades" },
  { "id": "park_wind-cave", "date_established": "1903-01-09T06:00:00Z" }
]'
Example Response
No Java example available, showing cURL
[
  {
    "id": "park_yosemite",
    "errors": []
  },
  {
    "id": "",
    "errors": [
      "Missing required key 'id'"
    ]
  },
  {
    "id": "park_wind-cave",
    "errors": []
  }
]

Example - A PATCH providing partial updates to 3 actual documents and attempting to update 3 erroneous documents.
No Node example available, showing cURL
curl -X PATCH 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '[
  { "id": "park_yosemite" },
  { "title": "Everglades" },
  { "id": "park_wind-cave", "date_established": "1903-01-09T06:00:00Z" }
]'
Example Response
No Node example available, showing cURL
[
  {
    "id": "park_yosemite",
    "errors": []
  },
  {
    "id": "",
    "errors": [
      "Missing required key 'id'"
    ]
  },
  {
    "id": "park_wind-cave",
    "errors": []
  }
]

Example - A PATCH providing partial updates to 3 actual documents and attempting to update 3 erroneous documents.
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'

documents = [ { "id": "park_yosemite" }, { "title": "Everglades" }, { "id": "park_wind-cave", "date_established": "1903-01-09T06:00:00Z" } ]

puts client.update_documents(engine_name, documents)

Example Response
[
  { 'id' => 'park_yosemite', 'errors' => [] },
  { 'id' => '', 'errors' => ["Missing required key 'id'"] },
  { 'id' => 'park_wind-cave', 'errors' => [] }
]

Example - A PATCH providing partial updates to 3 actual documents and attempting to update 3 erroneous documents.
No Python example available, showing cURL
curl -X PATCH 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '[
  { "id": "park_yosemite" },
  { "title": "Everglades" },
  { "id": "park_wind-cave", "date_established": "1903-01-09T06:00:00Z" }
]'
Example Response
No Python example available, showing cURL
[
  {
    "id": "park_yosemite",
    "errors": []
  },
  {
    "id": "",
    "errors": [
      "Missing required key 'id'"
    ]
  },
  {
    "id": "park_wind-cave",
    "errors": []
  }
]

Example - A PATCH providing partial updates to 3 actual documents and attempting to update 3 erroneous documents.
No Javascript example available, showing cURL
curl -X PATCH 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '[
  { "id": "park_yosemite" },
  { "title": "Everglades" },
  { "id": "park_wind-cave", "date_established": "1903-01-09T06:00:00Z" }
]'
Example Response
No Javascript example available, showing cURL
[
  {
    "id": "park_yosemite",
    "errors": []
  },
  {
    "id": "",
    "errors": [
      "Missing required key 'id'"
    ]
  },
  {
    "id": "park_wind-cave",
    "errors": []
  }
]

Delete Documents

Delete documents by id. Returns an array of JSON objects indicating the deleted status for each document. These contain an id property and a deleted property denoting whether the document was successfully deleted.

DELETE /api/as/v1/engines/{ENGINE_NAME}/documents
Example - Using DELETE to remove a pair of real documents and one example erroneous document.
curl -X DELETE 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '["park_zion", "park_yosemite", "does_not_exist"]'
Example Response
[
  {
    "id": "park_zion",
    "deleted": true
  },
  {
    "id": "park_yosmite",
    "deleted": true
  },
  {
    "id": "does_not_exist",
    "deleted": false
  }
]

Example - Using DELETE to remove a pair of real documents and one example erroneous document.
Client client = new Client("host-2376rb", "private-xxxxxxxxxxxxxxxxxxxx");

String engineName = "national-parks-demo"; String doc1_id = "park_zion"; String doc2_id = "park_yosmite";

client.destroyDocuments(engineName, Arrays.asList(doc1_id, doc2_id));

Example Response
List<Map<String, Object>>: [
  {
    "id": "park_zion",
    "deleted": true
  },
  {
    "id": "park_yosmite",
    "deleted": true
  }
]

Example - Using DELETE to remove a pair of real documents and one example erroneous document.
const client = new SwiftypeAppSearchClient('host-2376rb', 'private-xxxxxxxxxxxxxxxxxxxx')

const engineName = 'national-parks-demo'

documentIds = ['park_zion', 'park_yosmite', 'does_not_exist']

client.destroyDocuments(engineName, documentIds)

Example Response
[
  {
    "id": "park_zion",
    "deleted": true
  },
  {
    "id": "park_yosmite",
    "deleted": true
  },
  {
    "id": "does_not_exist",
    "deleted": false
  }
]

Example - Using DELETE to remove a pair of real documents and one example erroneous document.
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'

document_ids = %w[park_zion park_yosmite does_not_exist]

puts client.destroy_documents(engine_name, document_ids)

Example Response
[
  {
    'id' => 'park_zion',
    'deleted' => true
  },
  {
    'id' => 'park_yosmite',
    'deleted' => true
  },
  {
    'id' => 'does_not_exist',
    'deleted' => false
  }
]

Example - Using DELETE to remove a pair of real documents and one example erroneous document.
host_identifier = 'host-2376rb'
api_key = 'private-xxxxxxxxxxxxxxxxxxxx'
client = Client(host_identifier, api_key)

engine_name = 'national-parks-demo'

document_ids = ['park_zion', 'park_yosmite', 'does_not_exist']

client.destroy_documents(engine_name, document_ids)

Example Response
[
    {
        'id': 'park_zion',
        'deleted': True
    },
    {
        'id': 'park_yosmite',
        'deleted': True
    },
    {
        'id': 'does_not_exist',
        'deleted': False
    }
]

Example - Using DELETE to remove a pair of real documents and one example erroneous document.
No Javascript example available, showing cURL
curl -X DELETE 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '["park_zion", "park_yosemite", "does_not_exist"]'
Example Response
No Javascript example available, showing cURL
[
  {
    "id": "park_zion",
    "deleted": true
  },
  {
    "id": "park_yosmite",
    "deleted": true
  },
  {
    "id": "does_not_exist",
    "deleted": false
  }
]

Get Documents

Retrieves one or more documents by id. A null response will appear in the event that a requested document could not be found.

GET /api/as/v1/engines/{ENGINE_NAME}/documents

You have two options as to how you might send in your parameters:

JSON Object

A paginated array of JSON objects representing documents.

Example - Looking for three specific ids using JSON objects within the request body: "park_zion", "park_yosmite" and "does_not_exist".
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '["park_zion", "does_not_exist"]'
Example Response
[
  {
     "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
     }
  },
  null
]

Example - Looking for three specific ids using JSON objects within the request body: "park_zion", "park_yosmite" and "does_not_exist".
Client client = new Client("host-2376rb", "private-xxxxxxxxxxxxxxxxxxxx");

String engineName = "national-parks-demo"; String doc1_id = "park_zion"; String doc2_id = "does_not_exist;

client.getDocuments(engineName, Arrays.asList(doc1_id, doc2_id));

Example Response
List<Map<String, Object>>: [
  {
    "id": "park_zion",
    "description": "Yosemite features sheer granite cliffs, exceptionally tall waterfalls, and old-growth forests at a unique intersection of geology and hydrology. Half Dome and El Capitan rise from the park's centerpiece, the glacier-carved Yosemite Valley, and from its vertical walls drop Yosemite Falls, one of North America's tallest waterfalls at 2,425 feet (739 m) high. Three giant sequoia groves, along with a pristine wilderness in the heart of the Sierra Nevada, are home to a wide variety of rare plant and animal species."
    "nps_link": "https://www.nps.gov/yose/index.htm",
    "states": "California",
    "title": "Yosemite",
    "visitors": "5028868",
    "world_heritage_site": "false",
    "location": "37.83,-119.5",
    "acres": 761747.5,
    "square_km": "available",
    "date_established": "1890-10-01T05:00:00Z"
  }
]

Example - Looking for three specific ids using JSON objects within the request body: "park_zion", "park_yosmite" and "does_not_exist".
const client = new SwiftypeAppSearchClient('host-2376rb', 'private-xxxxxxxxxxxxxxxxxxxx')

const engineName = 'national-parks-demo'

documentIds = ['park_zion', 'does_not_exist']

client.getDocuments(engineName, documentIds)

Example Response
[
{
     "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
     }
  },
  null
]

Example - Looking for three specific ids using JSON objects within the request body: "park_zion", "park_yosmite" and "does_not_exist".
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'

document_ids = %w[park_zion does_not_exist]

puts client.get_documents(engine_name, document_ids)

Example Response
[
{
  "description" => "Located at the junction of the Colorado Plateau, Great Basin, and Mojave Desert, this park contains sandstone features such as mesas, rock towers, and canyons, including the Virgin River Narrows. The various sandstone formations and the forks of the Virgin River create a wilderness divided into four ecosystems: desert, riparian, woodland, and coniferous forest.", "nps_link" => "https://www.nps.gov/zion/index.htm", "states" => ["Utah"], "title" => "Zion", "visitors" => "4295127", "world_heritage_site" => "false", "location" => "37.3,-113.05", "acres" => "147237.02", "square_km" => "595.8", "date_established" => "1919-11-19T06:00:00Z", "id" => "park_zion"
},
  nil
]

Example - Looking for three specific ids using JSON objects within the request body: "park_zion", "park_yosmite" and "does_not_exist".
host_identifier = 'host-2376rb'
api_key = 'private-xxxxxxxxxxxxxxxxxxxx'
client = Client(host_identifier, api_key)

engine_name = 'national-parks-demo'

document_ids = ['park_zion', 'does_not_exist']

client.get_documents(engine_name, document_ids)

Example Response
[
  {
     "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
     }
  },
    None
]

Example - Looking for three specific ids using JSON objects within the request body: "park_zion", "park_yosmite" and "does_not_exist".
No Javascript example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '["park_zion", "does_not_exist"]'
Example Response
No Javascript example available, showing cURL
[
  {
     "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
     }
  },
  null
]

Query Parameters

A parameterized query.

Example - Looking for three specific ids using query parameters: "park_zion", "park_yosmite" and "does_not_exist".
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents?ids%5B%5D=park_yosmite&ids%5B%5D=park_zion&ids%5B%5D=does_not_exist' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
[
  {
     "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
     }
  },
  null
]

Example - Looking for three specific ids using query parameters: "park_zion", "park_yosmite" and "does_not_exist".
No Java example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents?ids%5B%5D=park_yosmite&ids%5B%5D=park_zion&ids%5B%5D=does_not_exist' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Java example available, showing cURL
[
  {
     "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
     }
  },
  null
]

Example - Looking for three specific ids using query parameters: "park_zion", "park_yosmite" and "does_not_exist".
No Node example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents?ids%5B%5D=park_yosmite&ids%5B%5D=park_zion&ids%5B%5D=does_not_exist' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Node example available, showing cURL
[
  {
     "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
     }
  },
  null
]

Example - Looking for three specific ids using query parameters: "park_zion", "park_yosmite" and "does_not_exist".
No Ruby example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents?ids%5B%5D=park_yosmite&ids%5B%5D=park_zion&ids%5B%5D=does_not_exist' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Ruby example available, showing cURL
[
  {
     "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
     }
  },
  null
]

Example - Looking for three specific ids using query parameters: "park_zion", "park_yosmite" and "does_not_exist".
No Python example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents?ids%5B%5D=park_yosmite&ids%5B%5D=park_zion&ids%5B%5D=does_not_exist' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Python example available, showing cURL
[
  {
     "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
     }
  },
  null
]

Example - Looking for three specific ids using query parameters: "park_zion", "park_yosmite" and "does_not_exist".
No Javascript example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents?ids%5B%5D=park_yosmite&ids%5B%5D=park_zion&ids%5B%5D=does_not_exist' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Javascript example available, showing cURL
[
  {
     "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
     }
  },
  null
]

List Documents

Retrieves all documents from an Engine.

GET /api/as/v1/engines/{ENGINE_NAME}/documents/list
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 100, and be will truncated if a larger size is requested. The default is the first page of documents with pagination at 100.

You have two options as to how you might send in your parameters:

JSON Object

A paginated array of JSON objects representing documents.

Example - Using JSON objects within the request body to see the second page of results, with a page size of 15 results per page.
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'
Example 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 - Using JSON objects within the request body to see the second page of results, with a page size of 15 results per page.
No Java example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'
Example 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 - Using JSON objects within the request body to see the second page of results, with a page size of 15 results per page.
No Node example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'
Example 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 - Using JSON objects within the request body to see the second page of results, with a page size of 15 results per page.
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'

options = { page: { current: 2, size: 15 } }

puts client.list_documents(engine_name, options)

Example Response
{
  'meta' => {
    'page' => {
      'current' => 2,
      'total_pages' => 4,
      'total_results' => 59,
      'size' => 15
    }
  },
  'results' => [
    {
      'description' =>
      'Death Valley is the hottest, lowest, and driest place in the United States. Daytime temperatures have topped 130 °F (54 °C) and it is home to Badwater Basin, the lowest elevation in North America. The park contains canyons, badlands,sand dunes, and mountain ranges, while more than 1000 species of plants grow in this geologic graben. Additional points of interest include salt flats, historic mines, and springs.',
      'nps_link' => 'https://www.nps.gov/deva/index.htm',
      'states' => %w[California Nevada],
      'title' => 'Death Valley',
      'visitors' => '1296283',
      'world_heritage_site' => 'false',
      'location' => '36.24,-116.82',
      'acres' => '3373063.14',
      'square_km' => '13650.3',
      'date_established' => '1994-10-31T06:00:00Z',
      'id' => 'park_death-valley'
    },
    ## Truncated!
  ]
}

Example - Using JSON objects within the request body to see the second page of results, with a page size of 15 results per page.
No Python example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'
Example 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 - Using JSON objects within the request body to see the second page of results, with a page size of 15 results per page.
No Javascript example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'
Example 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 Parameters

A parameterized query.

Example - Using Query Parameters to see the second page of results, with a page size of 15 results per page.
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example 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 - Using Query Parameters to see the second page of results, with a page size of 15 results per page.
No Java example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example 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 - Using Query Parameters to see the second page of results, with a page size of 15 results per page.
No Node example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example 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 - Using Query Parameters to see the second page of results, with a page size of 15 results per page.
No Ruby example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example 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 - Using Query Parameters to see the second page of results, with a page size of 15 results per page.
No Python example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example 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 - Using Query Parameters to see the second page of results, with a page size of 15 results per page.
No Javascript example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example 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!
  ]
}

Errors

Parsing the response code is not the optimal to determine whether or not an issue has arisen. Errors will be present in the response body. After making a request, a 200 will be returned assuming the request is not malformed or insecure. To determine the health of the request, note the presence of text within the errors array.

For example:

[
    {
        "id": null,
        "errors": [
            "Exceeds maximum allowed document size of 102400 bytes"
        ]
    }
]

Errors by Request Type

Each request type has a different indication that something is amiss.

POST and PATCH

A nested errors array is included as part of each document object...

[
  {
    "id": "123456",
    "errors": []
  }
]

The array may include one or more of the following errors:

Error MessageSolution
"Document limit exceeded: [PLAN_LIMIT]"Each plan has a different limit on total documents.
Standard: 50,000
Pro: 100,000
The limit is flexible and an extra 25,000 documents can be added by paying an additional S20 per month. If you reach your limit, you may upgrade your plan or contact Support to explore other options.
"Request exceeds maximum allowed limit of 100 documents"Only 100 documents may be added per request. If you need to add a batch, consider writing a script that sends documents in sets of 100.
"Exceeds maximum allowed document size of 102400 bytes"Each document must be less than 102400 bytes or 102.4 kilobytes. The larger the request, the more time it shall take. Consider breaking POST requests into smaller request batches.
"JSON must be an array or hash"Unstructured JSON data is not permitted. Ensure you have encapsulated your object in an array [] or a hash {}. If you are using query parameters, ensure that ids is followed with %5D%5B - this is an array, but escaped: ?ids%5D%5B=.
"Invalid field type: id must not be blank"Any field type may be blank except for the id. If want an id to be generated for you, you may omit the field. If you include the field, it must contain a value.
"Invalid field type: id must be less than 800 characters"The id field is limited to 800 characters. That should be plenty!
"Name can only contain lowercase letters, numbers, and underscores"Any field type may be blank except for the id. If you want an id to be generated for you, you may omit the field. If you include the field, it must contain a value.
"Invalid field value: Value '[VALUE]' cannot be parsed as a float"When a field type is set to number, the value must be a floating point integer.
"Invalid field value: Value '[VALUE]' cannot be parsed as a date (RFC 3339)"When a field type is set to date, the value string must resemble a string formatted to RFC3339. You may omit time, but the date at minimum must be provided: YYYY-MM-DD.
"Invalid field value: Value '[VALUE]' cannot be parsed as a location"When a field type is set to geolocation, the value string must be formatted according to lat/long: "37.7894758,-122.3940638"
"Can only update existing fields and [FIELD] is not included in the schema."A PATCH can not be used to create new fields, only update them. A POST may be used to create new fields.
"Missing required key 'id'"The document id must be included so that the API knows which document you are trying to use your PATCH against.
DELETE

The deleted field will indicate the status of your request, true for success and false for failure.

{
  "id": "does_not_exist",
  "deleted": false
}
GET

A null value will be returned within the response array when a document could not be found:

[
  {
     "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
     }
  },
  null
]

What's Next?

You should have a solid grip on indexing basics: adding data to your Engine, indexing and then building a schema. You likely already know how to create, adjust, or destroy your Engines, but if not then that is a great next step. Otherwise, Search is where you should venture. Alternatively, if you want to adjust your Schema on account of new Field Types, that would be a valuable information.


Stuck? Looking for help? Contact Support!