Skip to main content

Using the AddSearch Indexing API

All Indexing API endpoints require authentication. See the Authentication documentation for details.

Create a New Document​

Use this endpoint to add a new document to your index. A random ID will be generated for it.

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

Request headers​

  • Content-Type: application/json
  • Authentication headers (see Authentication docs)

Request body​

Provide the document details as JSON. Example:

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

Notes on fields​

  • custom_fields (optional): Key-value pairs representing custom document properties. Supported data types are text, integer, and double. Dates must be Unix timestamps (integers).

Important​

If you want to specify the document ID yourself or generate it from the URL, use the Update Document endpoint instead.

Response​

  • Returns HTTP 201 Created on success.
  • The Location header contains the URL of the newly created document.
  • Document availability may take a few seconds.

Retrieve a Document​

Fetch a single document by its document ID.

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

Response example​

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

Update an Existing Document or Create with Predefined ID​

Use this endpoint to update a document or create a new document with a specified ID or URL.

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

or

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

Request body examples​

With document ID in URL:

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

Or, include id or url fields in the JSON if omitting document ID from the URL:

{
  "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
  }
}

Document identification rules​

  • If the URL contains the document ID, that ID is used.
  • Else, if the id field is present, use it.
  • Otherwise, the ID is generated as the MD5 checksum of the url.

Supported fields​

  • url (optional): The document's URL.
  • id (optional): Unique document identifier.
  • custom_fields (optional): Key-value pairs, supporting text, integer, or double values.

Response​

  • Returns HTTP 202 Accepted on successful queuing.
  • Changes take a few seconds to become visible.

Batch Update Documents​

Update or create multiple documents in a single request.

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

Request headers​

  • Content-Type: application/json

Request body example​

{
  "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
      }
    }
  ]
}

Limits and notes​

  • Maximum request body size is 1 MB.
  • Each document must have either a url or id field.
  • If id is missing, the document ID is the MD5 checksum of the url.
  • Existing documents with matching IDs will be replaced entirely.

Response​

  • Returns HTTP 202 Accepted if the batch update is queued successfully.

Delete a Document​

Remove a document by its ID.

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

Response​

  • Returns HTTP 202 Accepted on successful queuing of deletion.

Delete Multiple Documents​

Delete multiple documents by specifying their IDs in the request body.

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

Request body example​

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

Response​

  • Returns HTTP 202 Accepted after queuing all delete operations.

For detailed authentication setup, refer to the API Authentication guide.