> ## Documentation Index
> Fetch the complete documentation index at: https://codebyahmed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin Reviews API — Approve and Reject Customer Reviews

> View, approve, or reject customer reviews from the admin moderation queue. Rejected reviews are hidden from the public storefront.

The Admin Reviews API gives you complete control over customer review moderation. You can list all reviews regardless of approval state, inspect individual reviews, toggle their visibility by approving or rejecting them, and permanently delete reviews that violate your content policies. This API exposes the full admin projection of each review, including the `is_approved` flag that is hidden from public endpoints.

<Info>
  Reviews are **auto-approved** the moment a customer submits them. Every new review arrives in an approved state and is immediately visible on the storefront. Use this API to retroactively moderate content — approving reviews reinstates their visibility while rejecting them removes them from the public product page.
</Info>

<Note>
  Before making any write request, call `GET /auth/csrf-token` to obtain a CSRF token and pass it in the `x-csrf-token` header alongside your session cookie.
</Note>

***

## Authentication

All admin review endpoints require:

* A valid `session` cookie (obtained via `POST /auth/login`)
* ADMIN or SUPER\_ADMIN role
* `x-csrf-token` header on all PATCH and DELETE requests

***

## List Reviews

Retrieve a paginated list of all reviews, including unapproved entries that are hidden from customers. Filter by approval state, rating, and search term. Sort by creation date or rating.

**`GET /admin/reviews`**

<ParamField query="page" type="integer" default="1">
  Page number (1-based).
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Items per page. Minimum 1, maximum 100.
</ParamField>

<ParamField query="search" type="string">
  Free-text search across review content (trimmed, max 100 characters).
</ParamField>

<ParamField query="is_approved" type="string">
  Filter by approval state. Use `"true"` for approved, `"false"` for unapproved, or `"all"` to return both. Omitting this parameter defaults to returning all states.
</ParamField>

<ParamField query="rating" type="integer">
  Filter by exact rating value. Integer from 1 to 5.
</ParamField>

<ParamField query="include_deleted" type="string" default="false">
  Set to `"true"` to include soft-deleted reviews.
</ParamField>

<ParamField query="sort" type="string" default="-created_at">
  Sort field. Prefix with `-` for descending. Options: `created_at`, `-created_at`, `rating`, `-rating`.
</ParamField>

<Tip>
  To work the moderation queue, filter with `is_approved=false`. This returns every review that customers have flagged or that has been retroactively rejected — giving you a focused list of content awaiting a decision.
</Tip>

<CodeGroup>
  ```bash List Unapproved Reviews theme={null}
  curl -X GET "https://api.example.com/api/v1/admin/reviews?is_approved=false&sort=-created_at" \
    -H "Cookie: session=<your-session-token>"
  ```

  ```bash List All Reviews theme={null}
  curl -X GET "https://api.example.com/api/v1/admin/reviews?is_approved=all&page=1&limit=20" \
    -H "Cookie: session=<your-session-token>"
  ```
</CodeGroup>

**Response `200 OK`**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "public_id": "rev_01H",
      "product_public_id": "prd_01H",
      "user_public_id": "usr_01H",
      "rating": 2,
      "title": "Disappointed",
      "comment": "Arrived damaged. Would not recommend.",
      "is_approved": false,
      "images": [],
      "created_at": "2024-06-10T14:22:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 7,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}
```

***

## Get Review Detail

Fetch a single review in any state, including unapproved or previously deleted entries with all attached images. Use this to inspect the full content of a review before making a moderation decision.

**`GET /admin/reviews/{review_public_id}`**

<ParamField path="review_public_id" type="string" required>
  The review's public ID (prefix: `rev_`).
</ParamField>

**Response `200 OK`**

```json theme={null}
{
  "success": true,
  "data": {
    "public_id": "rev_01H",
    "product_public_id": "prd_01H",
    "user_public_id": "usr_01H",
    "rating": 2,
    "title": "Disappointed",
    "comment": "Arrived damaged. Would not recommend.",
    "is_approved": false,
    "images": [
      {
        "image_url": "https://ik.imagekit.io/demo/reviews/damage.jpg",
        "alt_text": "Damaged packaging"
      }
    ],
    "created_at": "2024-06-10T14:22:00.000Z"
  }
}
```

***

## Moderate a Review

Approve or reject a review by updating its `is_approved` flag. You can also correct the rating, title, or comment as part of the same request — useful for minor editorial fixes before approving borderline content. At least one field must be supplied.

**`PATCH /admin/reviews/{review_public_id}`**

<ParamField path="review_public_id" type="string" required>
  The review's public ID (prefix: `rev_`).
</ParamField>

<ParamField body="is_approved" type="boolean">
  Set to `true` to make the review visible on the storefront, or `false` to hide it.
</ParamField>

<ParamField body="rating" type="integer">
  Corrected rating value. Integer from 1 to 5.
</ParamField>

<ParamField body="title" type="string | null">
  Updated title (max 255 characters). Pass `null` to clear the title.
</ParamField>

<ParamField body="comment" type="string | null">
  Updated comment (max 5000 characters). Pass `null` to clear the comment.
</ParamField>

<CodeGroup>
  ```bash Approve a Review theme={null}
  CSRF=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
    -H "Cookie: session=<your-session-token>" \
    | jq -r '.data.csrf_token')

  curl -X PATCH "https://api.example.com/api/v1/admin/reviews/rev_01H" \
    -H "Cookie: session=<your-session-token>" \
    -H "x-csrf-token: $CSRF" \
    -H "Content-Type: application/json" \
    -d '{"is_approved": true}'
  ```

  ```bash Reject a Review theme={null}
  CSRF=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
    -H "Cookie: session=<your-session-token>" \
    | jq -r '.data.csrf_token')

  curl -X PATCH "https://api.example.com/api/v1/admin/reviews/rev_01H" \
    -H "Cookie: session=<your-session-token>" \
    -H "x-csrf-token: $CSRF" \
    -H "Content-Type: application/json" \
    -d '{"is_approved": false}'
  ```
</CodeGroup>

**Response `200 OK`**

```json theme={null}
{
  "success": true,
  "data": {
    "public_id": "rev_01H",
    "product_public_id": "prd_01H",
    "user_public_id": "usr_01H",
    "rating": 2,
    "title": "Disappointed",
    "comment": "Arrived damaged. Would not recommend.",
    "is_approved": true,
    "images": [],
    "created_at": "2024-06-10T14:22:00.000Z"
  }
}
```

| Status Code | Meaning                                   |
| ----------- | ----------------------------------------- |
| `200`       | Review updated successfully.              |
| `400`       | No fields supplied, or validation failed. |
| `401`       | Missing or expired session.               |
| `403`       | Insufficient role.                        |
| `404`       | Review not found.                         |

***

## Delete a Review

Permanently hard-delete a review and all its attached images. Unlike the customer-facing delete endpoint — which performs a soft delete — this operation is **irreversible**. Use it for reviews that violate content policies and should not be recoverable.

**`DELETE /admin/reviews/{review_public_id}`**

<ParamField path="review_public_id" type="string" required>
  The review's public ID (prefix: `rev_`).
</ParamField>

<Warning>
  Admin deletion is a **hard delete**. The review and all its images are permanently removed and cannot be recovered. The customer who wrote the review will be able to submit a new review for the same product after deletion.
</Warning>

<CodeGroup>
  ```bash cURL theme={null}
  CSRF=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
    -H "Cookie: session=<your-session-token>" \
    | jq -r '.data.csrf_token')

  curl -X DELETE "https://api.example.com/api/v1/admin/reviews/rev_01H" \
    -H "Cookie: session=<your-session-token>" \
    -H "x-csrf-token: $CSRF"
  ```
</CodeGroup>

Returns `204 No Content` on success.

| Status Code | Meaning                     |
| ----------- | --------------------------- |
| `204`       | Review permanently deleted. |
| `401`       | Missing or expired session. |
| `403`       | Insufficient role.          |
| `404`       | Review not found.           |

***

## Endpoint Summary

<CardGroup cols={2}>
  <Card title="GET /admin/reviews" icon="list">
    List all reviews including unapproved. Filter by `is_approved=false` for the moderation queue.
  </Card>

  <Card title="GET /admin/reviews/:id" icon="eye">
    Fetch a single review in any state with all images attached.
  </Card>

  <Card title="PATCH /admin/reviews/:id" icon="shield-check">
    Approve or reject a review, optionally editing its content.
  </Card>

  <Card title="DELETE /admin/reviews/:id" icon="trash">
    Permanently hard-delete a review and its images.
  </Card>
</CardGroup>