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

A list of up to 100 documents. Documents are dictionaries 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

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

Example
curl -X POST 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '[
    {
        "id": "1",
        "make": "Toyota",
        "model": "4RUNNER",
        "year": "2017"
    },
    {
        "id": "2",
        "make": "Ford",
        "model": "Fiesta",
        "year": "2018"
    },
    {
        "make": "Toyota",
        "model": "RAV4",
        "year": "2014"
    }
]'
Example Response
[
    {
        "id": "1",
        "errors": []
    },
    {
        "id": "2",
        "errors": []
    },
    {
        "id": "doc-5aeb6d70c9f92961cbf35223",
        "errors": []
    }
]

Delete Documents

Delete documents by id.

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

Payload

A list of document ids.

Returns

A list of document delete status objects. These contain an id property and a deleted property denoting whether the document was successfully deleted.

Example
curl -X DELETE 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '["1", "2", "does_not_exist"]'
Example Response
[
    {
        "id": "1",
        "deleted": true
    },
    {
        "id": "2",
        "deleted": true
    },
    {
        "id": "does_not_exist",
        "deleted": false
    }
]

Get Documents

Retrieves documents by id.

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

Payload

A list of document ids.

Example
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '["1", "2", "does_not_exist"]'
Example Response
[
    {
        "make": "Toyota",
        "model": "4RUNNER",
        "year": "2017",
        "id": "1"
    },
    {
        "make": "Ford",
        "model": "Fiesta",
        "year": "2018",
        "id": "2"
    },
    null
]

Returns

A list of dictionaries representing documents. Documents that do not exist are represented by null.