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? Explore the Indexing Documents guide.


Create (index), update, delete, and display documents.

Authentication

For authentication, the Documents endpoint requires...

  1. A Host Identifier: [HOST_IDENTIFIER]
  2. The name of your Engine: [ENGINE]
  3. A Private API Key: [PRIVATE_API_KEY]
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.

The key is the field name and the value is the content.

Requests, when successful, return a 200 response code.

This indicates that the batch has been received, and indexing will begin.

The documents are indexed asynchronously.

There will be a processing delay before they are available to your Engine.

Key points to creating documents:

  • Documents are sent via an array and are independently accepted and indexed, or rejected.

  • A 200 response and an empty errors array denotes a successful index.

  • If no id is provided, a unique id will be generated.

  • A document is created each time content is received without an id - beware duplicates!

  • A document will be updated - not created - if its id already exists within a document.

  • If the Engine has not seen the field before, then it will create a new field of type text.

  • Fields cannot be named: external_id, engine_id, highlight, or, and, not, any, all, none.

  • There is a 100 document per request limit; each document must be less than 100kb.

  • An indexing request may not exceed 10mb.

For schema design principles, consult the API Overview.

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 '[
  {
    "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": [
      "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"
  }
]'
Example Response
[
  {
    "id": "park_death-valley",
    "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 = [ { "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": [ "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" } ]

client.indexDocuments(engineName, documents)

Example Response
[
  {
    "id": "park_death-valley",
    "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 = [ { "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": [ "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" } ]

puts client.index_documents(engine_name, documents)

Example Response
[
  {
    'id' => 'park_death-valley',
    '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 = [ { "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": [ "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" } ]

client.index_documents(engine_name, documents)

Example Response
[
    {
        'id': 'park_death-valley',
        '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 '[
  {
    "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": [
      "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"
  }
]'
Example Response
No Javascript example available, showing cURL
[
  {
    "id": "park_death-valley",
    "errors": []
  }
]

Partial Update (PATCH)

Update specific document fields by id and field.

The id is required and new fields cannot 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.

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
JSON Object

A paginated array of JSON objects representing documents.

Example - Looking for two specific ids using JSON objects within the request body: "park_zion" 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
[
  {
    "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"
  },
  null
]

Example - Looking for two specific ids using JSON objects within the request body: "park_zion" 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 two specific ids using JSON objects within the request body: "park_zion" 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
[
  {
    "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"
  },
  null
]

Example - Looking for two specific ids using JSON objects within the request body: "park_zion" 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 two specific ids using JSON objects within the request body: "park_zion" 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
[
  {
    "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"
  },
  null
]

Example - Looking for two specific ids using JSON objects within the request body: "park_zion" 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
[
  {
    "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"
  },
  null
]

Query Parameters

A parameterized query.

Example - Looking for two specific ids using query parameters: "park_zion" 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_zion&ids%5B%5D=does_not_exist' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
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"
  },
  null
]

Example - Looking for two specific ids using query parameters: "park_zion" 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_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
[
  {
    "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"
  },
  null
]

Example - Looking for two specific ids using query parameters: "park_zion" 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_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
[
  {
    "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"
  },
  null
]

Example - Looking for two specific ids using query parameters: "park_zion" 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_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
[
  {
    "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"
  },
  null
]

Example - Looking for two specific ids using query parameters: "park_zion" 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_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
[
  {
    "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"
  },
  null
]

Example - Looking for two specific ids using query parameters: "park_zion" 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_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
[
  {
    "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"
  },
  null
]

List Documents

Lists up to 10,000 documents.

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": 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": [
        "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"
    },
    {
      "description": "Centered on Denali, the tallest mountain in North America, Denali is serviced by a single road leading to Wonder Lake. Denali and other peaks of the Alaska Range are covered with long glaciers and boreal forest. Wildlife includes grizzly bears, Dall sheep, caribou, and gray wolves.",
      "nps_link": "https://www.nps.gov/dena/index.htm",
      "states": [
        "Alaska"
      ],
      "title": "Denali",
      "visitors": "587412",
      "world_heritage_site": "false",
      "location": "63.33,-150.5",
      "acres": "4740911.16",
      "square_km": "19185.8",
      "date_established": "1917-02-26T06:00:00Z",
      "id": "park_denali"
    },
    # ... 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": 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": [
        "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"
    },
    {
      "description": "Centered on Denali, the tallest mountain in North America, Denali is serviced by a single road leading to Wonder Lake. Denali and other peaks of the Alaska Range are covered with long glaciers and boreal forest. Wildlife includes grizzly bears, Dall sheep, caribou, and gray wolves.",
      "nps_link": "https://www.nps.gov/dena/index.htm",
      "states": [
        "Alaska"
      ],
      "title": "Denali",
      "visitors": "587412",
      "world_heritage_site": "false",
      "location": "63.33,-150.5",
      "acres": "4740911.16",
      "square_km": "19185.8",
      "date_established": "1917-02-26T06:00:00Z",
      "id": "park_denali"
    },
    # ... 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": 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": [
        "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"
    },
    {
      "description": "Centered on Denali, the tallest mountain in North America, Denali is serviced by a single road leading to Wonder Lake. Denali and other peaks of the Alaska Range are covered with long glaciers and boreal forest. Wildlife includes grizzly bears, Dall sheep, caribou, and gray wolves.",
      "nps_link": "https://www.nps.gov/dena/index.htm",
      "states": [
        "Alaska"
      ],
      "title": "Denali",
      "visitors": "587412",
      "world_heritage_site": "false",
      "location": "63.33,-150.5",
      "acres": "4740911.16",
      "square_km": "19185.8",
      "date_established": "1917-02-26T06:00:00Z",
      "id": "park_denali"
    },
    # ... 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": 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": [
        "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"
    },
    {
      "description": "Centered on Denali, the tallest mountain in North America, Denali is serviced by a single road leading to Wonder Lake. Denali and other peaks of the Alaska Range are covered with long glaciers and boreal forest. Wildlife includes grizzly bears, Dall sheep, caribou, and gray wolves.",
      "nps_link": "https://www.nps.gov/dena/index.htm",
      "states": [
        "Alaska"
      ],
      "title": "Denali",
      "visitors": "587412",
      "world_heritage_site": "false",
      "location": "63.33,-150.5",
      "acres": "4740911.16",
      "square_km": "19185.8",
      "date_established": "1917-02-26T06:00:00Z",
      "id": "park_denali"
    },
    # ... 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": 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": [
        "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"
    },
    {
      "description": "Centered on Denali, the tallest mountain in North America, Denali is serviced by a single road leading to Wonder Lake. Denali and other peaks of the Alaska Range are covered with long glaciers and boreal forest. Wildlife includes grizzly bears, Dall sheep, caribou, and gray wolves.",
      "nps_link": "https://www.nps.gov/dena/index.htm",
      "states": [
        "Alaska"
      ],
      "title": "Denali",
      "visitors": "587412",
      "world_heritage_site": "false",
      "location": "63.33,-150.5",
      "acres": "4740911.16",
      "square_km": "19185.8",
      "date_established": "1917-02-26T06:00:00Z",
      "id": "park_denali"
    },
    # ... 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": 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": [
        "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"
    },
    {
      "description": "Centered on Denali, the tallest mountain in North America, Denali is serviced by a single road leading to Wonder Lake. Denali and other peaks of the Alaska Range are covered with long glaciers and boreal forest. Wildlife includes grizzly bears, Dall sheep, caribou, and gray wolves.",
      "nps_link": "https://www.nps.gov/dena/index.htm",
      "states": [
        "Alaska"
      ],
      "title": "Denali",
      "visitors": "587412",
      "world_heritage_site": "false",
      "location": "63.33,-150.5",
      "acres": "4740911.16",
      "square_km": "19185.8",
      "date_established": "1917-02-26T06:00:00Z",
      "id": "park_denali"
    },
    # ... 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": 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": [
        "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"
    },
    {
      "description": "Centered on Denali, the tallest mountain in North America, Denali is serviced by a single road leading to Wonder Lake. Denali and other peaks of the Alaska Range are covered with long glaciers and boreal forest. Wildlife includes grizzly bears, Dall sheep, caribou, and gray wolves.",
      "nps_link": "https://www.nps.gov/dena/index.htm",
      "states": [
        "Alaska"
      ],
      "title": "Denali",
      "visitors": "587412",
      "world_heritage_site": "false",
      "location": "63.33,-150.5",
      "acres": "4740911.16",
      "square_km": "19185.8",
      "date_established": "1917-02-26T06:00:00Z",
      "id": "park_denali"
    },
    # ... 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": 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": [
        "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"
    },
    {
      "description": "Centered on Denali, the tallest mountain in North America, Denali is serviced by a single road leading to Wonder Lake. Denali and other peaks of the Alaska Range are covered with long glaciers and boreal forest. Wildlife includes grizzly bears, Dall sheep, caribou, and gray wolves.",
      "nps_link": "https://www.nps.gov/dena/index.htm",
      "states": [
        "Alaska"
      ],
      "title": "Denali",
      "visitors": "587412",
      "world_heritage_site": "false",
      "location": "63.33,-150.5",
      "acres": "4740911.16",
      "square_km": "19185.8",
      "date_established": "1917-02-26T06:00:00Z",
      "id": "park_denali"
    },
    # ... 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": 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": [
        "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"
    },
    {
      "description": "Centered on Denali, the tallest mountain in North America, Denali is serviced by a single road leading to Wonder Lake. Denali and other peaks of the Alaska Range are covered with long glaciers and boreal forest. Wildlife includes grizzly bears, Dall sheep, caribou, and gray wolves.",
      "nps_link": "https://www.nps.gov/dena/index.htm",
      "states": [
        "Alaska"
      ],
      "title": "Denali",
      "visitors": "587412",
      "world_heritage_site": "false",
      "location": "63.33,-150.5",
      "acres": "4740911.16",
      "square_km": "19185.8",
      "date_established": "1917-02-26T06:00:00Z",
      "id": "park_denali"
    },
    # ... 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": 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": [
        "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"
    },
    {
      "description": "Centered on Denali, the tallest mountain in North America, Denali is serviced by a single road leading to Wonder Lake. Denali and other peaks of the Alaska Range are covered with long glaciers and boreal forest. Wildlife includes grizzly bears, Dall sheep, caribou, and gray wolves.",
      "nps_link": "https://www.nps.gov/dena/index.htm",
      "states": [
        "Alaska"
      ],
      "title": "Denali",
      "visitors": "587412",
      "world_heritage_site": "false",
      "location": "63.33,-150.5",
      "acres": "4740911.16",
      "square_km": "19185.8",
      "date_established": "1917-02-26T06:00:00Z",
      "id": "park_denali"
    },
    # ... 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": 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": [
        "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"
    },
    {
      "description": "Centered on Denali, the tallest mountain in North America, Denali is serviced by a single road leading to Wonder Lake. Denali and other peaks of the Alaska Range are covered with long glaciers and boreal forest. Wildlife includes grizzly bears, Dall sheep, caribou, and gray wolves.",
      "nps_link": "https://www.nps.gov/dena/index.htm",
      "states": [
        "Alaska"
      ],
      "title": "Denali",
      "visitors": "587412",
      "world_heritage_site": "false",
      "location": "63.33,-150.5",
      "acres": "4740911.16",
      "square_km": "19185.8",
      "date_established": "1917-02-26T06:00:00Z",
      "id": "park_denali"
    },
    # ... Truncated!
  ]
}

Errors

After making the request, a 200 will be returned assuming the request is not malformed.

To determine the status of the request, the errors array will describe any issues:

// The response code will be 200!
[
    {
        "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 indicates request status: 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:

[
  {
    "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"
  },
  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 or check out the App Search community forum!