Skip to content

POST /update

Adding new documents or updating existing ones in 904Labs Cloud Indexing Service requires a call to the /update endpoint. In both cases, documents are expected as a list of JSON dictionaries residing in parameter docs for a particular locale. Documents that already exist in the index will be updated, those that do not yet exist will be added to the index (upsert behavior). The response of the endpoint contains a status for each document in the list indicating either success or failure. For documents that failed to index, we also provide a short message describing the reason of failure.

Note

Documents are expected to adhere to 940Labs Cloud Indexing schema structure.

Note

The maximum size of a request is set to 1MB. If your application requires a larger threshold, please get in touch.

Request

HTTP request

POST https://api.904labs.com/sls/{customer_id}/update?api_key={api_key}

Request attributes

Attribute Type Description
customer_id string (required) Your customer ID

Request parameters

Parameter Type Description
api_key string (required) Your API key

Request body

Property name Value Description
docs list (required) List of JSON dictionaries. Each dictionary is a document to be inserted. Documents should adhere to the Cloud Indexing schema.
locale string (required) Country and language of the shop/site in ll_TT format, where ll is the language in ISO 639-1 format and TT is the territory in ISO 3166 format (e.g., en_US).

Example request

In the example request below, the customer is trying to index two documents. Document document_id_1 follows the Cloud Indexing schema, but document document_id_2 does not. It won't be possible to index the second document. The expected behavior here is that document_id_1 will be indexed but document_id_2 will not.

import requests as r

headers = {"content-type": "application/json"}
URL_INDEX = "https://api.904labs.com/sls/CUSTOMER_ID/update"
params = {
    "api_key": "APIKEY"
}
payload = {
    "docs": [
        {
            "id": "document_id_1",
            "type": "page",
            "search_result_data": { ... },
            "search_data": [{ ... }],
            "category": { ... },
            "product_data": { ... },
            "synonyms": [ ... ],
            "number_sort": { ... },
            "string_sort": { ... }
         },
         {
            "id": "document_id_2",
            "type": "page",
            "non_existent_field": [{ ... }],
            "category": { ... },
            "product_data": { ... },
            "synonyms": [ ... ]
         }
    ],
    "locale": "en_US"
}

response = r.post(URL_INDEX, json=payload, headers=headers, params=params)

Response

{
    "success_messages": [
        {
            "id": string,
            "processed": boolean,
            "message": string
        }
    ],
    "error_messages": [
        {
            "id": string,
            "processed": boolean,
            "message": string
        }
    ]
}
Property name Value Description
success_messages list A list of dictionaries, each item in the list corresponds to an input document successfully processed.
error_messages list A list of dictionaries, each item in the list corresponds to an input document that failed.
id string The ID of the document.
processed boolean A flag indicating whether the document was processed (inserted, or updated) into the index (true) or not (false).
message string Details of what happened to the document. In case of an error, this property contains the error message.

Example response

In the example response below, we receive statuses for all documents that were sent for indexing. Status messages are divided into two lists, success_messages for successes and error_messages for failures, for easier parsing. document_id_2 is returned into the error list with a message describing the reason of failure; here it is that non_existent_field is not in the schema. document_id_1 was successfully indexed, and it is found in the success list.

{
    "success_messages": [
        {
            "id": "document_id_1",
            "processed": true,
            "message": "Document processed"
        }
    ],
    "error_messages": [
        {
            "id": "document_id_2",
            "processed": false,
            "message": "ERROR: [doc=document_id_2] unknown field 'non_existent_field'"
        }
    ]
}