Reviews API

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:

Parameter	Type	Description
documents	Array of objects	An array of review documents (max 100 per request).

Each document has the following fields:

Parameter	Type	Required	Description
_id	string	Yes	The product document ID this review belongs to
summary	string	Yes	A 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:

Parameter	Type	Required	Description
index_name	string	Yes	The name of your index
document_id	string	Yes	The 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:

Parameter	Type	Required	Description
ids	array	Yes	Array 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:

Parameter	Type	Required	Description
index_name	string	Yes	The name of your index
job_id	string	Yes	The 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}'