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

Documents are the content within engines. The API allows you to create, update, and delete documents.

Create or Update Documents

Creates documents or updates existing documents by id. Documents are indexed or rejected independently: all valid documents in the payload will be indexed and all invalid documents will be rejected.

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

Payload

An array of up to 100 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. id is a unique identifier for documents. If the id of a document matches an existing document, the existing document will be replaced with the contents of the document in the request. If an id is not given, a unique one will be generated automatically.

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

Returns

An array of JSON objects indicating the index status for each document. These contain an id property and an errors property that contains an array of validation errors. An empty errors array denotes a successful index of the document. Returns an error if the api key does not have write permissions, the request is too big, or the engine does not exist.

Example
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
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
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
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
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
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": []
  }
]

Delete Documents

Delete documents by id.

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

Payload

An array of document ids.

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.

Example
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
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
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
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
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
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 documents by id.

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

Payload

An array of document ids.

Returns

An array of JSON objects representing documents. Documents that do not exist are represented by null.

Example
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
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
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
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
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
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
]

List Documents

Retrieves all documents from an engine.

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

Arguments

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.

Returns

A paginated array of JSON objects representing documents.

Example
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'
Example Response
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 2,
      "size": 100
    }
  },
  "results": [
    {
      "make": "Toyota",
      "model": "4RUNNER",
      "year": "2017",
      "id": "441376183"
    },
    {
      "make": "Ford",
      "model": "Fiesta",
      "year": "2018",
      "id": "781226450"
    }
  ]
}

Example
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'
Example Response
No Java example available, showing cURL
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 2,
      "size": 100
    }
  },
  "results": [
    {
      "make": "Toyota",
      "model": "4RUNNER",
      "year": "2017",
      "id": "441376183"
    },
    {
      "make": "Ford",
      "model": "Fiesta",
      "year": "2018",
      "id": "781226450"
    }
  ]
}

Example
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'
Example Response
No Node example available, showing cURL
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 2,
      "size": 100
    }
  },
  "results": [
    {
      "make": "Toyota",
      "model": "4RUNNER",
      "year": "2017",
      "id": "441376183"
    },
    {
      "make": "Ford",
      "model": "Fiesta",
      "year": "2018",
      "id": "781226450"
    }
  ]
}

Example
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'
Example Response
No Ruby example available, showing cURL
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 2,
      "size": 100
    }
  },
  "results": [
    {
      "make": "Toyota",
      "model": "4RUNNER",
      "year": "2017",
      "id": "441376183"
    },
    {
      "make": "Ford",
      "model": "Fiesta",
      "year": "2018",
      "id": "781226450"
    }
  ]
}

Example
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'
Example Response
No Python example available, showing cURL
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 2,
      "size": 100
    }
  },
  "results": [
    {
      "make": "Toyota",
      "model": "4RUNNER",
      "year": "2017",
      "id": "441376183"
    },
    {
      "make": "Ford",
      "model": "Fiesta",
      "year": "2018",
      "id": "781226450"
    }
  ]
}

Example
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'
Example Response
No Javascript example available, showing cURL
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 2,
      "size": 100
    }
  },
  "results": [
    {
      "make": "Toyota",
      "model": "4RUNNER",
      "year": "2017",
      "id": "441376183"
    },
    {
      "make": "Ford",
      "model": "Fiesta",
      "year": "2018",
      "id": "781226450"
    }
  ]
}

What's Next?

Your Documents are the life-blood of your engines. You likely already know how to create, adjust or destroy your Engines, but if not that may be a great next step. Otherwise, Search is where you should venture. Alternatively, if you want to see how your documents are performing, Analytics has your insights waiting.


Stuck? Looking for help? Contact Support!