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

# GET /reviews

> Fetch cached review data for an ASIN

# GET /api/v1/reviews

Fetch cached review data for an Amazon product.

> **Free & Unlimited**: This endpoint doesn't count toward your quota. Only refresh jobs are metered.

## Request

**Headers**:

| Header        | Value                 | Required |
| ------------- | --------------------- | -------- |
| Authorization | `Bearer YOUR_API_KEY` | Yes      |

**Query Parameters**:

| Parameter | Type   | Required | Description                  |
| --------- | ------ | -------- | ---------------------------- |
| asin      | string | Yes      | Amazon ASIN to fetch reviews |

## Response (200 OK)

```json theme={null}
{
  "asin": "B08N5WRWNW",
  "title": "Example Product Title",
  "imageUrl": "https://m.media-amazon.com/images/I/...",
  "marketplace": "amazon.de",
  "reviewCount": 156,
  "reviews": [
    {
      "id": 12345,
      "amazonReviewId": "R1ABC123DEF",
      "title": "Great product!",
      "content": "I've been using this for a month and it's exactly what I needed...",
      "date": "2026-01-15T00:00:00.000Z",
      "isTopReview": true,
      "country": "DE",
      "scrapedAt": "2026-02-02T10:31:00.000Z"
    }
  ],
  "lastScraped": "2026-02-02T10:31:00.000Z",
  "cached": true
}
```

| Field       | Type    | Description                        |
| ----------- | ------- | ---------------------------------- |
| asin        | string  | Amazon ASIN                        |
| title       | string  | Product title                      |
| imageUrl    | string  | Product image URL                  |
| marketplace | string  | Amazon marketplace                 |
| reviewCount | number  | Total number of cached reviews     |
| reviews     | array   | Array of review objects            |
| lastScraped | string  | ISO 8601 timestamp of last refresh |
| cached      | boolean | Whether data is from cache         |

### Review Object

| Field          | Type    | Description                    |
| -------------- | ------- | ------------------------------ |
| id             | number  | Internal review ID             |
| amazonReviewId | string  | Amazon's review ID             |
| title          | string  | Review headline                |
| content        | string  | Full review text               |
| date           | string  | Review date (ISO 8601)         |
| isTopReview    | boolean | Whether this is a "Top Review" |
| country        | string  | Reviewer's country code        |
| scrapedAt      | string  | When review was scraped        |

## Response (404 Not Found)

When no cached data exists for an ASIN:

```json theme={null}
{
  "asin": "B08N5WRWNW",
  "reviews": [],
  "cached": false,
  "message": "No cached data. Create a refresh job first."
}
```

## Errors

| Status | Error                   | Cause                             |
| ------ | ----------------------- | --------------------------------- |
| 400    | `Missing asin`          | asin query parameter not provided |
| 401    | `Invalid API key`       | Key doesn't exist or was revoked  |
| 404    | `No cached data`        | ASIN hasn't been refreshed yet    |
| 500    | `Internal server error` | Temporary backend/service issue   |

## Examples

**cURL**:

```bash theme={null}
curl "https://app.descripio.com/api/v1/reviews?asin=B08N5WRWNW" \
  -H "Authorization: Bearer dscr_abc123..."
```

**Python**:

```python theme={null}
import requests

response = requests.get(
    "https://app.descripio.com/api/v1/reviews",
    params={"asin": "B08N5WRWNW"},
    headers={"Authorization": "Bearer dscr_abc123..."}
)

data = response.json()

if data.get("cached"):
    print(f"Found {data['reviewCount']} reviews")
    for review in data["reviews"][:5]:
        print(f"- {review['title']}")
else:
    print("No cached data. Run a refresh job first.")
```

**JavaScript**:

```javascript theme={null}
const response = await fetch(
  'https://app.descripio.com/api/v1/reviews?asin=B08N5WRWNW',
  {
    headers: { 'Authorization': 'Bearer dscr_abc123...' }
  }
);

const data = await response.json();

if (data.cached) {
  console.log(`Found ${data.reviewCount} reviews`);
  data.reviews.slice(0, 5).forEach(r => console.log(`- ${r.title}`));
} else {
  console.log('No cached data. Run a refresh job first.');
}
```

## Notes

* **Caching**: Data persists until the next refresh job for that ASIN
* **Full Review Text**: Get up to 200 reviews per ASIN (10 pages recent + 10 pages helpful).
* **Free**: This endpoint is free and unlimited - only refresh jobs count toward quota


## OpenAPI

````yaml GET /api/v1/reviews
openapi: 3.1.0
info:
  title: Descripio Reviews API
  version: 1.1.0
  description: |
    OpenAPI contract aligned to implemented Next.js endpoints under `/api/v1`.
    Authentication uses `Authorization: Bearer <API_KEY>`.
servers:
  - url: https://app.descripio.com
    description: Production
security:
  - BearerApiKeyAuth: []
tags:
  - name: Reviews
  - name: Jobs
paths:
  /api/v1/reviews:
    get:
      tags:
        - Reviews
      summary: Get cached reviews for an ASIN
      operationId: getReviews
      parameters:
        - name: asin
          in: query
          required: true
          schema:
            type: string
            pattern: ^[A-Z0-9]{10}$
          example: B08N5WRWNW
      responses:
        '200':
          description: Cached reviews found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewsSuccessResponse'
        '400':
          description: Missing asin parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Missing asin parameter
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No cached data exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewsNotFoundResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ReviewsSuccessResponse:
      type: object
      required:
        - asin
        - reviewCount
        - reviews
        - cached
      properties:
        asin:
          type: string
          example: B08N5WRWNW
        title:
          type: string
          nullable: true
          example: Example Product Title
        imageUrl:
          type: string
          nullable: true
          example: https://m.media-amazon.com/images/I/example.jpg
        marketplace:
          type: string
          example: amazon.de
        reviewCount:
          type: integer
          example: 156
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/ReviewItem'
        lastScraped:
          type: string
          format: date-time
          nullable: true
          example: '2026-02-02T10:31:00.000Z'
        cached:
          type: boolean
          enum:
            - true
          example: true
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: Invalid API key
        message:
          type: string
          nullable: true
          example: Unable to process request. Please retry in a few moments.
        retryable:
          type: boolean
          nullable: true
          example: true
    ReviewsNotFoundResponse:
      type: object
      required:
        - asin
        - reviews
        - cached
        - message
      properties:
        asin:
          type: string
          example: B08N5WRWNW
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/ReviewItem'
          example: []
        cached:
          type: boolean
          enum:
            - false
          example: false
        message:
          type: string
          example: No cached data. Create a refresh job first.
    ReviewItem:
      type: object
      required:
        - id
        - amazonReviewId
        - title
        - content
        - date
        - isTopReview
        - country
        - scrapedAt
      properties:
        id:
          type: integer
          example: 12345
        amazonReviewId:
          type: string
          example: R1ABC123DEF
        title:
          type: string
          nullable: true
          example: Great product!
        content:
          type: string
          nullable: true
          example: I've been using this for a month and it's exactly what I needed.
        date:
          type: string
          format: date-time
          nullable: true
          example: '2026-01-15T00:00:00.000Z'
        isTopReview:
          type: boolean
          nullable: true
          example: true
        country:
          type: string
          nullable: true
          example: DE
        scrapedAt:
          type: string
          format: date-time
          nullable: true
          example: '2026-02-02T10:31:00.000Z'
  securitySchemes:
    BearerApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key passed in Authorization header as Bearer token.

````