Indexing Api

Please note that all the Indexing API endpoints require authentication as described here.

CREATE NEW DOCUMENT

POST /v2/indices/{index public key}/documents/

Creates a new document. A random id will be generated for the document. If you want to define the id for the document yourself, or if you want to automatically generate it with a url field, use the “Update Document” endpoint instead.

Payload

The content-type header of the request should be application/json. The request body should be a JSON object describing the document contents.

{
  "custom_fields": {
    "title": "Example product",
    "description": "Description for example product",
    "price_cents": 599,
    "average_customer_rating": 4.5
  }
}

Document fields

• custom_fields: Optional. A map of key value pairs for custom fields. Multiple datatypes are supported. See “Custom field data types” below.

Custom field data types

Data types for custom fields are automatically deduced from the content. Supported data types are:

• text
• integer
• double

Dates should be presented as unix timestamps with integer values.

Please note that once a custom field has been introduced with a specific data type, the data type can not be changed. Indexing a non-compatible value will fail. If you have picked a wrong data type, please introduce a custom field with a different name.

Response

On successful queing of document creation, the endpoint will return a response HTTP 201 Created, with a URL pointing to the created document in the response header “Location”. Please note that it might take few seconds for the document to become available.

GET DOCUMENT

GET /v2/indices/{index public key}/documents/{document id}

Retrieve the contents of a single document from the index

Response

{
  "id": "8700a03070a37982924597d6baa87be7",
  "custom_fields": {
    "title": "Example product",
    "description": "Description for example product",
    "price_cents": 599,
    "average_customer_rating": 4.5
  }
}

UPDATE EXISTING DOCUMENT

Updates existing document, or creates a new document with predefined URL or ID.

PUT /v2/indices/{index public key}/documents/{document id}

{
  "custom_fields": {
    "title": "Example product",
    "description": "Description for example product",
    "price_cents": 599,
    "average_customer_rating": 4.5
  }
}

You can omit the document id in the URL if you include either a document id or a “url” field in the document content:

PUT /v2/indices/{index public key}/documents/

{
  "url": "https://www.example.com/",
  "id": "8700a03070a37982924597d6baa87be7",
  "custom_fields": {
    "title": "Example product",
    "description": "Description for example product",
    "price_cents": 599,
    "average_customer_rating": 4.5
  }
}

If the URL does not contain the document id, the id of the document will be resolved be either

1) “id” field present in the document; or if the “id” is not present the
2) a md5 checksum of the “url” field in the document

Document fields

• url: Optional. The URL of the document.
• id: Optional. An unique identifier for the document.
• custom_fields: Optional. A map of key value pairs for custom fields. Multiple datatypes are supported. See “Custom field data types” below.

Response

On successful queuing of the update, returns a HTTP 202. Please note that it might take few seconds for the changes to become available.

BATCH UPDATE DOCUMENTS

PUT /v2/indices/{index public key}/documents:batch

Updates a batch of documents (or creates new documents with predefined ids).

Payload

The content-type header of the request should be application/json. The request body should be a JSON object, listing the documents inside an “documents” array.

{
  "documents": [
    {
      "url": "https://www.example.com/product1.html",
      "id": "8700a03070a37982924597d6baa87be7",
      "custom_fields": {
        "title": "Example product",
        "description": "Description for example product",
        "price_cents": 599,
        "average_customer_rating": 4.5
      }
    },
    {
      "url": "https://www.example.com/product2.html",
      "id": "d3b07384d113edec49eaa6238ad5ff00",
      "custom_fields": {
        "title": "Example product",
        "description": "Description for example product",
        "price_cents": 349,
        "average_customer_rating": 4.2
      }
    }
  ]
}

The maximum size of request body is limited to total of 1M bytes.

Each document in the array must contain either a url or an id field. If id is not present, then the md5 checksum of the url field will be used as such. If a document exists with a given id, it will be fully replaced by the given document.

DELETE DOCUMENT

DELETE /v2/indices/{index public key}/documents/{document id}

Removes a document from the index

Response

On successful queuing of the delete operation, returns a HTTP 202.

DELETE A BATCH OF DOCUMENTS

DELETE /v2/indices/{index public key}/documents:batch

Removes multiple documents from the index

Payload

The payload includes a list of document ids in an array.

{
  "documents": ["a9b9f04336ce0181a08e774e01113b31",
                      "68486f8ffd0f928de748de19b663c60a"]
}

Response

On successful queuing of the delete operations, returns a HTTP 202.