​
Overview

The Reviews API allows you to add, retrieve, and delete review data for products in your index. Reviews are stored asynchronously and can be used by the Conversational Agent to enrich product discovery with customer review insights. Each review is associated with a product document via its _id. When a user asks a question like “What do people say about this product?”, the system can pull the stored review data to generate informed, contextual responses.

​
Prerequisites

  • A Marqo Cloud account
  • Your Marqo API key
  • An existing ecommerce index with products (add products guide)

​
Endpoints

​
Add Reviews

Add review summaries for one or more products. This operation is asynchronous — the response contains a job ID that you can poll to check completion status. Endpoint: POST /indexes/{index_name}/agentic-search/reviews Headers:
  • Content-Type: application/json
  • Authorization: Bearer {api_key} (required)
Request Body:
ParameterTypeDescription
documentsArray of objectsAn array of review documents (max 100 per request).
Each document has the following fields:
ParameterTypeRequiredDescription
_idstringYesThe product document ID this review belongs to
summarystringYesA summary of customer reviews for this product
Example Request: 
curl -X POST 'https://ecom.marqo-ep.ai/api/v1/indexes/my-ecom-store/agentic-search/reviews' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {api_key}' \
  --data '{
    "documents": [
      {
        "_id": "product-001",
        "summary": "Customers love the comfort and fit. Most reviewers highlight the breathable fabric and true-to-size fit. Some mention that colors may fade slightly after several washes."
      },
      {
        "_id": "product-002",
        "summary": "Highly rated for durability and style. Reviewers appreciate the premium materials and versatile design. A few customers noted the price is on the higher end."
      }
    ]
  }'
Example Response: The response contains a job ID. Use this to poll the Get Job Status endpoint to check completion. 
{
  "jobId": "d93d82fa-a82a-4b08-b583-04866e8b89e1"
}

​
Get Review

Retrieve the review summary for a specific product document. Endpoint: GET /indexes/{index_name}/agentic-search/reviews/{document_id} Headers:
  • Authorization: Bearer {api_key} (required)
Path Parameters:
ParameterTypeRequiredDescription
index_namestringYesThe name of your index
document_idstringYesThe product document ID
Example Request: 
curl 'https://ecom.marqo-ep.ai/api/v1/indexes/my-ecom-store/agentic-search/reviews/product-001' \
  --header 'Authorization: Bearer {api_key}'
Example Response: 
{
  "_id": "product-001",
  "summary": "Customers love the comfort and fit. Most reviewers highlight the breathable fabric and true-to-size fit. Some mention that colors may fade slightly after several washes.",
  "updated": 1708419012000
}

​
Delete Reviews

Delete reviews for one or more products. This operation is asynchronous — the response contains a job ID that you can poll to check completion status. Endpoint: DELETE /indexes/{index_name}/agentic-search/reviews Headers:
  • Content-Type: application/json
  • Authorization: Bearer {api_key} (required)
Request Body:
ParameterTypeRequiredDescription
idsarrayYesArray of product document IDs to delete reviews for (max 100 per request)
Example Request: 
curl -X DELETE 'https://ecom.marqo-ep.ai/api/v1/indexes/my-ecom-store/agentic-search/reviews' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {api_key}' \
  --data '{
    "ids": ["product-001", "product-002"]
  }'
Example Response: 
{
  "jobId": "2fe8eafd-c619-42ab-9acb-7f15182984ae"
}

​
Get Job Status

Check the status of an asynchronous add or delete operation. Endpoint: GET /indexes/{index_name}/agentic-search/reviews/jobs/{job_id} Headers:
  • Authorization: Bearer {api_key} (required)
Path Parameters:
ParameterTypeRequiredDescription
index_namestringYesThe name of your index
job_idstringYesThe job ID returned from an add or delete reviews request
Example Request: 
curl 'https://ecom.marqo-ep.ai/api/v1/indexes/my-ecom-store/agentic-search/reviews/jobs/d93d82fa-a82a-4b08-b583-04866e8b89e1' \
  --header 'Authorization: Bearer {api_key}'