Skip to main content

Create a New Document in an Index

Use the following API endpoint to add a new document to your AddSearch index:

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

Overview​

This endpoint creates a new document in the provided index. If you do not specify a document ID, the system generates a unique ID automatically using an MD5 hash of the URL. To set a custom ID or use the URL as the ID, use the Update Document endpoint instead.

Request Payload​

Send a JSON object in the request body describing the document. It includes standard fields supported by the system and any custom fields you want to add.

Example payload:

{
  "thumbnail_external_src": "https://www.example.com/thumbnail-image.jpg",
  "url": "https://www.example.com",
  "language": "en",
  "title": "Page title",
  "main_content": "The page content",
  "doc_date": "2023-12-31",
  "custom_fields": {
    "description": "Description for example product",
    "price_cents": 599,
    "average_customer_rating": 4.5,
    "release_date": 1589200255
  }
}

Fields Description​

FieldDescriptionTypeNotes
idDocument identifierstringOptional for this endpoint. If omitted, an ID will be generated based on the document URL.
thumbnail_external_srcURL of the thumbnail imagestringImage used as a thumbnail for the document.
urlDocument's full URLstringExample: "https://www.example.com"
languageDocument language codestringTwo-letter ISO language code, e.g., "en", "de", "es"
titleDocument titlestringTypically matches the HTML title tag content
main_contentMain textual content of the documentstringSearch highlighting and indexing are based on this field
doc_dateDocument's datestringSupports formats like "2023-12-31", ISO 8601 date-time (e.g., "2023-12-31T12:10:30Z"), or epoch milliseconds (e.g., "1704004677000")
custom_fieldsAdditional metadata for filtering, sorting, and displayobjectKey-value pairs with string, integer, or double values. See Custom fields

Document Fields Details​

  • Standard fields: Predefined keys with values as strings.
  • Custom fields: User-defined key-value pairs supporting multiple data types (strings, integers, doubles).

Example with standard and custom fields:

{
  "thumbnail_external_src": "https://www.example.com/thumbnail-image.jpg",
  "url": "https://www.example.com/",
  "language": "en",
  "title": "An example article title",
  "main_content": "The text content of the article. Search highlights use this content.",
  "doc_date": "2023-12-31",
  "custom_fields": {
    "description": "Description for example product",
    "price_cents": 599,
    "average_customer_rating": 4.5,
    "release_date": 1589200255,
    "image_url": "https://www.example.com/page.png",
    "article_categories": ["Blog post", "Article"]
  }
}

Custom Field Data Types​

AddSearch detects the custom field data type automatically from the provided value. Supported types include:

  • string
  • integer
  • double

Dates should be stored as UNIX timestamps in integer format.

Important: Once you assign a type to a custom field, it cannot be changed. Using unsupported data types will cause indexing to fail. To correct this, create a new custom field with a different name.

Response​

A successful creation returns HTTP status 201 Created.

The response includes a Location header with the URL of the created document.

Note: It may take a few seconds before the document becomes searchable.

See Also​