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:

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 rent-a-car Engine.
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '[
  {
    "id": "441376183",
    "make": "Toyota",
    "model": "4RUNNER",
    "year": "2017"
  },
  {
    "id": "781226450",
    "make": "Ford",
    "model": "Fiesta",
    "year": "2018"
  },
  {
    "make": "Toyota",
    "model": "RAV4",
    "year": "2014"
  }
]'
Example Response
[
  {
    "id": "441376183",
    "errors": []
  },
  {
    "id": "781226450",
    "errors": []
  },
  {
    "id": "doc-5aeb6d70c9f92961cbf35223",
    "errors": []
  }
]

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

String engineName = "rent-a-car";

Map<String, Object> doc1 = new HashMap<>(); doc1.put("id", "441376183"); doc1.put("make", "Toyota"); doc1.put("model", "4RUNNER"); doc1.put("year", "2017");

Map<String, Object> doc2 = new HashMap<>(); doc2.put("id", "781226450"); doc2.put("make", "Ford"); doc2.put("model", "Fiesta"); doc2.put("year", "2018");

Map<String, Object> doc3 = new HashMap<>(); doc2.put("make", "Toyota"); doc2.put("model", "RAV4"); doc2.put("year", "2014");

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

Example Response
List<Map<String, Object>>: [
  {
    "id": "441376183",
    "errors": []
  },
  {
    "id": "781226450",
    "errors": []
  },
  {
    "id": "doc-5aeb6d70c9f92961cbf35223",
    "errors": []
  }
]

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

const engineName = 'rent-a-car'

const documents = [ { id: '441376183', make: 'Toyota', model: '4RUNNER', year: '2017' }, { id: '781226450', make: 'Ford', model: 'Fiesta', year: '2018' }, { make: 'Toyota', model: 'RAV4', year: '2014' } ]

client.indexDocuments(engineName, documents)

Example Response
[
  {
    "id": "441376183",
    "errors": []
  },
  {
    "id": "781226450",
    "errors": []
  },
  {
    "id": "doc-5aeb6d70c9f92961cbf35223",
    "errors": []
  }
]

Example - A POST request adding three documents to the rent-a-car Engine.
host_identifier = 'host-2376rb'
api_key = 'private-xxxxxxxxxxxxxxxxxxxx'
client = SwiftypeAppSearch::Client.new(host_identifier: host_identifier, api_key: api_key)

engine_name = 'rent-a-car'

documents = [ { id: '441376183', make: 'Toyota', model: '4RUNNER', year: '2017' }, { id: '781226450', make: 'Ford', model: 'Fiesta', year: '2018' }, { make: 'Toyota', model: 'RAV4', year: '2014' } ]

puts client.index_documents(engine_name, documents)

Example Response
[
  {
    'id' => '441376183',
    'errors' => []
  },
  {
    'id' => '781226450',
    'errors' => []
  },
  {
    'id' => 'doc-5aeb6d70c9f92961cbf35223',
    'errors' => []
  }
]

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

engine_name = 'rent-a-car' query = 'toyota'

documents = [ { 'id': '441376183', 'make': 'Toyota', 'model': '4RUNNER', 'year': '2017' }, { 'id': '781226450', 'make': 'Ford', 'model': 'Fiesta', 'year': '2018' }, { 'make': 'Toyota', 'model': 'RAV4', 'year': '2014' } ]

client.index_documents(engine_name, documents)

Example Response
[
    {
        'id': '441376183',
        'errors': []
    },
    {
        'id': '781226450',
        'errors': []
    },
    {
        'id': 'doc-5aeb6d70c9f92961cbf35223',
        'errors': []
    }
]

Example - A POST request adding three documents to the rent-a-car Engine.
No Javascript example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '[
  {
    "id": "441376183",
    "make": "Toyota",
    "model": "4RUNNER",
    "year": "2017"
  },
  {
    "id": "781226450",
    "make": "Ford",
    "model": "Fiesta",
    "year": "2018"
  },
  {
    "make": "Toyota",
    "model": "RAV4",
    "year": "2014"
  }
]'
Example Response
No Javascript example available, showing cURL
[
  {
    "id": "441376183",
    "errors": []
  },
  {
    "id": "781226450",
    "errors": []
  },
  {
    "id": "doc-5aeb6d70c9f92961cbf35223",
    "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 'http://host-2376rb.swiftype.com/api/as/v1/engines/gems/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '[
  { "id": "doc-5b3a0b74add56b31fad9da07", "name": "apple" },
  { "id": "doc-5b34da64add56b13e9a66222", "name": ["so", "many", "names"] },
  { "id": "doc-5b34d43fadd56b13e9a6621d", "color": "red" },
  { "name": "banana" },
  { "id": "doc-5b3a031dadd56b31fad9da01", "downloads": "not a number" },
  { "id": "123", "name": "lemon" }
]'
Example Response
[
  {
    "id": "doc-5b3a0b74add56b31fad9da07",
    "errors": []
  },
  {
    "id": "doc-5b34da64add56b13e9a66222",
    "errors": []
  },
  {
    "id": "doc-5b34d43fadd56b13e9a6621d",
    "errors": [
      "Can only update existing fields and 'color' is not included in the schema."
    ]
  },
  {
    "id": "",
    "errors": [
      "Missing required key 'id'"
    ]
  },
  {
    "id": "doc-5b3a031dadd56b31fad9da01",
    "errors": [
      "Invalid field value: Value 'not a number' cannot be parsed as a float"
    ]
  },
  {
    "id": "123",
    "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 'http://host-2376rb.swiftype.com/api/as/v1/engines/gems/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '[
  { "id": "doc-5b3a0b74add56b31fad9da07", "name": "apple" },
  { "id": "doc-5b34da64add56b13e9a66222", "name": ["so", "many", "names"] },
  { "id": "doc-5b34d43fadd56b13e9a6621d", "color": "red" },
  { "name": "banana" },
  { "id": "doc-5b3a031dadd56b31fad9da01", "downloads": "not a number" },
  { "id": "123", "name": "lemon" }
]'
Example Response
No Java example available, showing cURL
[
  {
    "id": "doc-5b3a0b74add56b31fad9da07",
    "errors": []
  },
  {
    "id": "doc-5b34da64add56b13e9a66222",
    "errors": []
  },
  {
    "id": "doc-5b34d43fadd56b13e9a6621d",
    "errors": [
      "Can only update existing fields and 'color' is not included in the schema."
    ]
  },
  {
    "id": "",
    "errors": [
      "Missing required key 'id'"
    ]
  },
  {
    "id": "doc-5b3a031dadd56b31fad9da01",
    "errors": [
      "Invalid field value: Value 'not a number' cannot be parsed as a float"
    ]
  },
  {
    "id": "123",
    "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 'http://host-2376rb.swiftype.com/api/as/v1/engines/gems/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '[
  { "id": "doc-5b3a0b74add56b31fad9da07", "name": "apple" },
  { "id": "doc-5b34da64add56b13e9a66222", "name": ["so", "many", "names"] },
  { "id": "doc-5b34d43fadd56b13e9a6621d", "color": "red" },
  { "name": "banana" },
  { "id": "doc-5b3a031dadd56b31fad9da01", "downloads": "not a number" },
  { "id": "123", "name": "lemon" }
]'
Example Response
No Node example available, showing cURL
[
  {
    "id": "doc-5b3a0b74add56b31fad9da07",
    "errors": []
  },
  {
    "id": "doc-5b34da64add56b13e9a66222",
    "errors": []
  },
  {
    "id": "doc-5b34d43fadd56b13e9a6621d",
    "errors": [
      "Can only update existing fields and 'color' is not included in the schema."
    ]
  },
  {
    "id": "",
    "errors": [
      "Missing required key 'id'"
    ]
  },
  {
    "id": "doc-5b3a031dadd56b31fad9da01",
    "errors": [
      "Invalid field value: Value 'not a number' cannot be parsed as a float"
    ]
  },
  {
    "id": "123",
    "errors": []
  }
]

Example - A PATCH providing partial updates to 3 actual documents and attempting to update 3 erroneous documents.
No Ruby example available, showing cURL
curl -X PATCH 'http://host-2376rb.swiftype.com/api/as/v1/engines/gems/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '[
  { "id": "doc-5b3a0b74add56b31fad9da07", "name": "apple" },
  { "id": "doc-5b34da64add56b13e9a66222", "name": ["so", "many", "names"] },
  { "id": "doc-5b34d43fadd56b13e9a6621d", "color": "red" },
  { "name": "banana" },
  { "id": "doc-5b3a031dadd56b31fad9da01", "downloads": "not a number" },
  { "id": "123", "name": "lemon" }
]'
Example Response
No Ruby example available, showing cURL
[
  {
    "id": "doc-5b3a0b74add56b31fad9da07",
    "errors": []
  },
  {
    "id": "doc-5b34da64add56b13e9a66222",
    "errors": []
  },
  {
    "id": "doc-5b34d43fadd56b13e9a6621d",
    "errors": [
      "Can only update existing fields and 'color' is not included in the schema."
    ]
  },
  {
    "id": "",
    "errors": [
      "Missing required key 'id'"
    ]
  },
  {
    "id": "doc-5b3a031dadd56b31fad9da01",
    "errors": [
      "Invalid field value: Value 'not a number' cannot be parsed as a float"
    ]
  },
  {
    "id": "123",
    "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 'http://host-2376rb.swiftype.com/api/as/v1/engines/gems/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '[
  { "id": "doc-5b3a0b74add56b31fad9da07", "name": "apple" },
  { "id": "doc-5b34da64add56b13e9a66222", "name": ["so", "many", "names"] },
  { "id": "doc-5b34d43fadd56b13e9a6621d", "color": "red" },
  { "name": "banana" },
  { "id": "doc-5b3a031dadd56b31fad9da01", "downloads": "not a number" },
  { "id": "123", "name": "lemon" }
]'
Example Response
No Python example available, showing cURL
[
  {
    "id": "doc-5b3a0b74add56b31fad9da07",
    "errors": []
  },
  {
    "id": "doc-5b34da64add56b13e9a66222",
    "errors": []
  },
  {
    "id": "doc-5b34d43fadd56b13e9a6621d",
    "errors": [
      "Can only update existing fields and 'color' is not included in the schema."
    ]
  },
  {
    "id": "",
    "errors": [
      "Missing required key 'id'"
    ]
  },
  {
    "id": "doc-5b3a031dadd56b31fad9da01",
    "errors": [
      "Invalid field value: Value 'not a number' cannot be parsed as a float"
    ]
  },
  {
    "id": "123",
    "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 'http://host-2376rb.swiftype.com/api/as/v1/engines/gems/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '[
  { "id": "doc-5b3a0b74add56b31fad9da07", "name": "apple" },
  { "id": "doc-5b34da64add56b13e9a66222", "name": ["so", "many", "names"] },
  { "id": "doc-5b34d43fadd56b13e9a6621d", "color": "red" },
  { "name": "banana" },
  { "id": "doc-5b3a031dadd56b31fad9da01", "downloads": "not a number" },
  { "id": "123", "name": "lemon" }
]'
Example Response
No Javascript example available, showing cURL
[
  {
    "id": "doc-5b3a0b74add56b31fad9da07",
    "errors": []
  },
  {
    "id": "doc-5b34da64add56b13e9a66222",
    "errors": []
  },
  {
    "id": "doc-5b34d43fadd56b13e9a6621d",
    "errors": [
      "Can only update existing fields and 'color' is not included in the schema."
    ]
  },
  {
    "id": "",
    "errors": [
      "Missing required key 'id'"
    ]
  },
  {
    "id": "doc-5b3a031dadd56b31fad9da01",
    "errors": [
      "Invalid field value: Value 'not a number' cannot be parsed as a float"
    ]
  },
  {
    "id": "123",
    "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/rent-a-car/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '["441376183", "781226450", "does_not_exist"]'
Example Response
[
  {
    "id": "441376183",
    "deleted": true
  },
  {
    "id": "781226450",
    "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 = "rent-a-car"; String doc1_id = "441376183"; String doc2_id = "781226450";

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

Example Response
List<Map<String, Object>>: [
  {
    "id": "441376183",
    "deleted": true
  },
  {
    "id": "781226450",
    "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 = 'rent-a-car'

documentIds = ['441376183', '781226450', 'does_not_exist']

client.destroyDocuments(engineName, documentIds)

Example Response
[
  {
    "id": "441376183",
    "deleted": true
  },
  {
    "id": "781226450",
    "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 = 'rent-a-car'

document_ids = %w[441376183 781226450 does_not_exist]

puts client.destroy_documents(engine_name, document_ids)

Example Response
[
  {
    'id' => '441376183',
    'deleted' => true
  },
  {
    'id' => '781226450',
    '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 = 'rent-a-car'

document_ids = ['441376183', '781226450', 'does_not_exist']

client.destroy_documents(engine_name, document_ids)

Example Response
[
    {
        'id': '441376183',
        'deleted': True
    },
    {
        'id': '781226450',
        '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/rent-a-car/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '["441376183", "781226450", "does_not_exist"]'
Example Response
No Javascript example available, showing cURL
[
  {
    "id": "441376183",
    "deleted": true
  },
  {
    "id": "781226450",
    "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: "441376183", "781226450" and "does_not_exist".
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '["441376183", "781226450", "does_not_exist"]'
Example Response
[
  {
    "make": "Toyota",
    "model": "4RUNNER",
    "year": "2017",
    "id": "441376183"
  },
  {
    "make": "Ford",
    "model": "Fiesta",
    "year": "2018",
    "id": "781226450"
  },
  null
]

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

String engineName = "rent-a-car"; String doc1_id = "441376183"; String doc2_id = "781226450";

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

Example Response
List<Map<String, Object>>: [
  {
    "id": "441376183",
    "make": "Toyota",
    "model": "4RUNNER",
    "year": "2017",
    "color": "blue",
    "drivetrain": "AWD",
    "category": "Full-Size SUV",
    "seats": 7,
    "status": "available",
    "daily_rate": 79,
    "ac": true,
    "mileage_policy": "unlimited",
    "current_location": "37.6213, -122.3790"
  },
  {
    "id": "781226450",
    "make": "Ford",
    "model": "Fiesta",
    "year": "2018",
    "color": "red",
    "drivetrain": "FWD",
    "category": "Compact",
    "seats": 5,
    "status": "available",
    "daily_rate": 27,
    "ac": true,
    "mileage_policy": "unlimited",
    "current_location": "37.6213, -122.3790"
  }
]

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

const engineName = 'rent-a-car'

documentIds = ['441376183', '781226450', 'does_not_exist']

client.getDocuments(engineName, documentIds)

Example Response
[
  {
    "make": "Toyota",
    "model": "4RUNNER",
    "year": "2017",
    "id": "441376183"
  },
  {
    "make": "Ford",
    "model": "Fiesta",
    "year": "2018",
    "id": "781226450"
  },
  null
]

Example - Looking for three specific ids using JSON objects within the request body: "441376183", "781226450" 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 = 'rent-a-car'

document_ids = %w[441376183 781226450 does_not_exist]

puts client.get_documents(engine_name, document_ids)

Example Response
[
  {
    'make' => 'Toyota',
    'model' => '4RUNNER',
    'year' => '2017',
    'id' => '441376183'
  },
  {
    'make' => 'Ford',
    'model' => 'Fiesta',
    'year' => '2018',
    'id' => '781226450'
  },
  null
]

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

engine_name = 'rent-a-car'

document_ids = ['441376183', '781226450', 'does_not_exist']

client.get_documents(engine_name, document_ids)

Example Response
[
    {
        'model': '4RUNNER',
        'make': 'Toyota',
        'year': '2017',
        'id': '441376183'
    }, {
        'model': 'Fiesta',
        'make': 'Ford',
        'year': '2018',
        'id': '781226450'
    },
    None
]

Example - Looking for three specific ids using JSON objects within the request body: "441376183", "781226450" and "does_not_exist".
No Javascript example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '["441376183", "781226450", "does_not_exist"]'
Example Response
No Javascript example available, showing cURL
[
  {
    "make": "Toyota",
    "model": "4RUNNER",
    "year": "2017",
    "id": "441376183"
  },
  {
    "make": "Ford",
    "model": "Fiesta",
    "year": "2018",
    "id": "781226450"
  },
  null
]

Query Parameters

A parameterized query.

Example - Looking for three specific ids using query parameters: "441376183", "781226450" and "does_not_exist".
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/documents?ids%5B%5D=781226450&ids%5B%5D=441376183&ids%5B%5D=does_not_exist' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
[
  {
    "make": "Toyota",
    "model": "4RUNNER",
    "year": "2017",
    "id": "441376183"
  },
  {
    "make": "Ford",
    "model": "Fiesta",
    "year": "2018",
    "id": "781226450"
  },
  null
]

Example - Looking for three specific ids using query parameters: "441376183", "781226450" and "does_not_exist".
No Java example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/documents?ids%5B%5D=781226450&ids%5B%5D=441376183&ids%5B%5D=does_not_exist' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Java example available, showing cURL
[
  {
    "make": "Toyota",
    "model": "4RUNNER",
    "year": "2017",
    "id": "441376183"
  },
  {
    "make": "Ford",
    "model": "Fiesta",
    "year": "2018",
    "id": "781226450"
  },
  null
]

Example - Looking for three specific ids using query parameters: "441376183", "781226450" and "does_not_exist".
No Node example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/documents?ids%5B%5D=781226450&ids%5B%5D=441376183&ids%5B%5D=does_not_exist' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Node example available, showing cURL
[
  {
    "make": "Toyota",
    "model": "4RUNNER",
    "year": "2017",
    "id": "441376183"
  },
  {
    "make": "Ford",
    "model": "Fiesta",
    "year": "2018",
    "id": "781226450"
  },
  null
]

Example - Looking for three specific ids using query parameters: "441376183", "781226450" and "does_not_exist".
No Ruby example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/documents?ids%5B%5D=781226450&ids%5B%5D=441376183&ids%5B%5D=does_not_exist' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Ruby example available, showing cURL
[
  {
    "make": "Toyota",
    "model": "4RUNNER",
    "year": "2017",
    "id": "441376183"
  },
  {
    "make": "Ford",
    "model": "Fiesta",
    "year": "2018",
    "id": "781226450"
  },
  null
]

Example - Looking for three specific ids using query parameters: "441376183", "781226450" and "does_not_exist".
No Python example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/documents?ids%5B%5D=781226450&ids%5B%5D=441376183&ids%5B%5D=does_not_exist' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Python example available, showing cURL
[
  {
    "make": "Toyota",
    "model": "4RUNNER",
    "year": "2017",
    "id": "441376183"
  },
  {
    "make": "Ford",
    "model": "Fiesta",
    "year": "2018",
    "id": "781226450"
  },
  null
]

Example - Looking for three specific ids using query parameters: "441376183", "781226450" and "does_not_exist".
No Javascript example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/documents?ids%5B%5D=781226450&ids%5B%5D=441376183&ids%5B%5D=does_not_exist' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Javascript example available, showing cURL
[
  {
    "make": "Toyota",
    "model": "4RUNNER",
    "year": "2017",
    "id": "441376183"
  },
  {
    "make": "Ford",
    "model": "Fiesta",
    "year": "2018",
    "id": "781226450"
  },
  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/rent-a-car/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": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... 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/rent-a-car/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": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... 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/rent-a-car/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": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... 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 Ruby example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'
Example Response
No Ruby example available, showing cURL
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... Truncated!
  ]
}

Example - 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/rent-a-car/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": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... 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/rent-a-car/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": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... 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/rent-a-car/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": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... 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/rent-a-car/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": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... 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/rent-a-car/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": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... 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/rent-a-car/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": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... 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/rent-a-car/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": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... 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/rent-a-car/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": [
    {
      "make": "Toyota",
      "model": "RAV4",
      "year": "2014",
      "id": "doc-5b608021a1f2530a06cf0177"
    },
    # ... 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:

[
  {
    "make": "Toyota",
    "model": "4RUNNER",
    "year": "2017",
    "id": "441376183"
  },
  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!