Batch Update Documents via API

Use the AddSearch API to update multiple documents or create new documents with predefined IDs in a specific index.

Endpoint

PUT /v2/indices/{index_public_key}/documents:batch

Replace {index_public_key} with your index's public key.

Request Payload

The request body must be a JSON object with a single documents array. Each element in this array represents a document to add or update.

Example:

{
  "documents": [
    {
      "url": "https://www.example.com/product1.html",
      "id": "8700a03070a37982924597d6baa87be7",
      "thumbnail_external_src": "https://www.example.com/thumbnail-image.jpg",
      "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",
      "thumbnail_external_src": "https://www.example.com/another-thumbnail-image.jpg",
      "custom_fields": {
        "title": "Example product",
        "description": "Description for example product",
        "price_cents": 349,
        "average_customer_rating": 4.2
      }
    }
  ]
}

Document Fields

Field	Description	Type	Notes
documents	Array of documents to add or update	Array of objects	Contains multiple document objects
url	Document URL	String	Required if id is absent
id	Document identifier	String	MD5 hash of URL is used if absent; replaces existing entry
thumbnail_external_src	URL of thumbnail image	String	Optional; used as the document's thumbnail by default
Standard fields	See standard fields except url	Varies	Each field is a separate key-value pair
custom_fields	Key-value pairs of custom metadata	Object	Supported types: text, integer, double

Important Details

• The total request size must not exceed 1 megabyte (1M bytes).
• Each document must contain at least one of the two fields: url or id.
• If you supply the id, the document with that id is replaced entirely by the new document.
• If id is omitted, the server calculates the MD5 hash of the url to use as the document id.

Additional Resources

Refer to Standard Fields documentation for information on standard fields you can include.

---