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

Create a new document to the index.

By default, the Documents API endpoint creates a random id for each new document. If you want to define the id for the document or generate the id using the URL field, use the Update Document endpoint.

Payload

The request body should be a JSON object containing the standard and custom fields describing the document contents.

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

Field	Description	Type	Notes
id	Document's id	string	Document identifier, e.g. "1234" added as parameter in the request. If the id value is not set, it will be set as URL encoded with md5 hash.
thumbnail_external_src	Thumbnails's URL	string	A URL of an image used as a thumbnail for the document by default
url	Document's URL	string	E.g. "https://www.example.com"
language	Document's language	string	Two-letter language format, e.g. “en”, “de”, “es”.
title	Document's title	string	Document's title, e.g. content of the HTML title tag.
main_content	Document's content	string	Text content of the web page.
doc_date	Document's date	string	Supported formats are date: "2023-12-31", date and time: "2023-12-31T12:10:30Z" and epoch: "1704004677000".
custom_fields	Additional data used for result images, filtering and sorting search results	string, integer, double	E.g. "image_url": "https://www.example.com/thumbnail.png", "location": "London", "faculty": "Physics", "star-review": 5, "price_in_cents": 0.55. Visit the documentation for more information.

Document fields

• Standard fields consists of key value pairs for pre-defined standard fields. The type for all standard fields is string.
• Custom fields is a map of key-value pairs for custom fields. Multiple data types are supported. See “Custom field data types” below.

{
  "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. The automatic highlight in search results will only be generated from the content of this field.",
  "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

Data types for custom fields are automatically collected from the fields content/value. Supported data types are:

• string
• integer
• double

Dates as custom fields should be defined as UNIX timestamps with integer values.

Please note that once you have defined a specific data type for the custom field, the data type cannot be changed.

Indexing unsupported values will fail. If you have defined an unsupported data type, create a new custom field with a different name.

Response

A request to create a new document adds the document to a queue. On success, the endpoint will return a response HTTP 201 Created, with a URL pointing to the created document in the response header “Location.” It might take a few seconds for the document to become available.