Create or Update a Document in Your AddSearch Index

Use the AddSearch API to create a new document or update an existing one in your search index. This guide explains how to format your requests and the supported fields.

---

API Endpoints

Update or Create a Document by ID

Send a PUT request to:

/v2/indices/{index_public_key}/documents/{document_id}

Replace {index_public_key} with your index's public key and {document_id} with the document's ID.

Example request body:

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

Field	Description	Type	Notes
custom_fields	Map of custom key-value pairs	Object (text, integer, double)	Supported types: text, integer, double

---

Create or Update a Document Using URL or ID in the Payload

If you prefer, you can omit the document ID from the URL and instead include id or url fields inside the JSON payload.

Send a PUT request to:

/v2/indices/{index_public_key}/documents/

Example request body:

{
  "url": "https://www.example.com/",
  "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
  }
}

Field	Description	Type	Notes
url	Document's URL	string	Required if id is not provided
id	Document's identifier	string	MD5 hash of the URL or custom ID
thumbnail_external_src	URL of thumbnail image	string	Used as the document's thumbnail
Standard fields	See standard fields documentation	Various	Standard metadata, excluding URL
custom_fields	Map of custom key-value pairs	Object	Supported types: text, integer, double

Document Identification

When the document ID is not included in the URL:

1. The API uses the id field in the document content if provided.
2. If id is absent, the system calculates an MD5 checksum of the url field as the ID.

Document Fields

• Standard fields: Refer to the standard fields documentation for predefined searchable fields.

• Custom fields: Include additional metadata as key-value pairs supporting the following data types:

  • Text
  • Integer
  • Double

Dates must be provided as UNIX timestamps (integers).

Note: Once a custom field's data type is set, you cannot change it. Using unsupported data types causes indexing failures. Create new fields with different names to accommodate different data types.

Example document:

{
  "id": "123",
  "thumbnail_external_src": "https://www.example.com/thumbnail-image.jpg",
  "url": "https://www.example.com/page.html",
  "language": "en",
  "title": "An example article title",
  "main_content": "The text content of the article. Highlighting in search results uses this field.",
  "custom_fields": {
    "image_url": "https://www.example.com/page.png",
    "article_categories": ["Blog post", "Article"]
  }
}

Response

A successful request queues the document update and returns HTTP status code 202 Accepted.

Changes may take a few seconds to propagate and become visible in the search results.

---

For more details on standard fields, see Indexing Overview - Standard Fields.