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 (find your API key)
• An existing ecommerce index with products (add products guide)
• Review storage enabled for your index (contact Marqo). Until it is enabled, every endpoint on this page returns 400 Reviews index not configured

Authentication

All Reviews endpoints require an API key in the Authorization: Bearer {api_key} header. They do not accept the x-marqo-index-id credential used by shopper-facing endpoints; a request without an API key returns 401 Unauthorized. Call them from your backend so the key is never exposed in client-side code.

Adding and deleting reviews needs a Read-Write (or Admin) key. Reading a review or a job needs a Read key or higher. A key with insufficient scope returns 403 Insufficient API key scope.

Every endpoint accepts an optional channel query parameter (letters, numbers, hyphens, or underscores; maximum 64 characters) when Marqo has configured channel-specific agentic settings for your index. Omit it unless Marqo has asked you to use it.

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 (1 to 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. Must not be empty
metadata	object	No	Any additional JSON object to store alongside the summary (for example a rating or review count). Returned as-is by Get Review

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.",
        "metadata": {"averageRating": 4.6, "reviewCount": 128}
      },
      {
        "_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 request is accepted with status 202 and returns a job ID. Use it to poll the Get Job Status endpoint to check completion.

{
  "jobId": "d93d82fa-a82a-4b08-b583-04866e8b89e1"
}

Error Responses:

• 400 Invalid request: ... when the body fails validation (missing documents, an empty _id or summary, or more than 100 documents)
• 400 Reviews index not configured
• 401 Unauthorized
• 403 Insufficient API key scope

---

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",
  "reviewSummary": "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.",
  "metadata": {"averageRating": 4.6, "reviewCount": 128},
  "updated": 1708419012000
}

Response Fields:

• _id (string): The product document ID
• reviewSummary (string): The stored review summary. Note that the field is named reviewSummary in the response even though it is sent as summary when adding
• metadata (object): The metadata sent when the review was added. Absent when none was sent
• updated (number): Timestamp (milliseconds since epoch) when the review was last added or replaced

Error Responses:

• 404 Review summary not found for document: {document_id} when no review is stored for that product, including while an add job is still pending
• 400 Reviews index not configured
• 401 Unauthorized
• 403 Insufficient API key scope

---

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 (1 to 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:

The request is accepted and returns a job ID to poll with Get Job Status.

{
  "jobId": "2fe8eafd-c619-42ab-9acb-7f15182984ae"
}

Error Responses:

• 400 Invalid request: ... when the body fails validation (missing ids, an empty ID, or more than 100 IDs)
• 400 Reviews index not configured
• 401 Unauthorized
• 403 Insufficient API key scope

---

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}'

Example Response:

The response is the same job object returned by the index jobs endpoint. See Monitor Jobs for every field and the list of job statuses.

{
  "jobId": "d93d82fa-a82a-4b08-b583-04866e8b89e1",
  "jobType": "BULK",
  "jobStatus": "COMPLETED",
  "totalItems": 2,
  "processedItems": 2,
  "failedItems": 0,
  "createdAt": "2025-08-12T14:50:22.272035+00:00",
  "completedAt": "2025-08-12T14:50:35.980820+00:00"
}

Error Responses:

• 400 Reviews index not configured
• 401 Unauthorized
• 403 Insufficient API key scope