> ## 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.

# POST /reviews/refresh

> Trigger a review scraping job for an ASIN

# POST /api/v1/reviews/refresh

Trigger a review scraping job for an Amazon product.

## Request

**Headers**:

| Header        | Value                 | Required |
| ------------- | --------------------- | -------- |
| Authorization | `Bearer YOUR_API_KEY` | Yes      |
| Content-Type  | `application/json`    | Yes      |

**Body**:

```json theme={null}
{
  "asin": "B08N5WRWNW",
  "marketplace": "amazon.de"
}
```

| Field       | Type   | Required | Description                                             |
| ----------- | ------ | -------- | ------------------------------------------------------- |
| asin        | string | Yes      | Amazon ASIN (10 alphanumeric characters)                |
| marketplace | string | No       | Amazon marketplace (defaults to `amazon.de` if omitted) |

## Response (202 Accepted)

```json theme={null}
{
  "jobId": 2877,
  "asin": "B08N5WRWNW",
  "status": "queued",
  "message": "Review refresh job created successfully",
  "estimatedCompletionSeconds": 60
}
```

| Field                      | Type   | Description                            |
| -------------------------- | ------ | -------------------------------------- |
| jobId                      | number | Unique job ID (use to poll status)     |
| asin                       | string | The ASIN being processed               |
| status                     | string | Always `queued` for new jobs           |
| message                    | string | Human-readable confirmation            |
| estimatedCompletionSeconds | number | Typical completion time (\~60 seconds) |

## Errors

| Status | Error                        | Cause                                 | Solution                         |
| ------ | ---------------------------- | ------------------------------------- | -------------------------------- |
| 400    | `Invalid ASIN format`        | ASIN not 10 alphanumeric characters   | Verify ASIN format               |
| 401    | `Invalid API key`            | Key doesn't exist or was revoked      | Check your API key               |
| 402    | `Monthly quota exceeded`     | Used all refresh jobs for the month   | Wait for reset or upgrade plan   |
| 403    | `Marketplace not authorized` | Store doesn't have marketplace access | Add marketplace in dashboard     |
| 429    | `Rate limit exceeded`        | Too many requests per minute          | Wait 60 seconds                  |
| 429    | `Too many concurrent jobs`   | Concurrent job limit reached          | Wait for a job to complete       |
| 429    | `ASIN cooldown active`       | ASIN was refreshed recently           | Wait for cooldown (24h for Free) |
| 500    | `service_error`              | Temporary backend/service issue       | Retry after a short delay        |

## Examples

**cURL**:

```bash theme={null}
curl -X POST https://app.descripio.com/api/v1/reviews/refresh \
  -H "Authorization: Bearer dscr_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "asin": "B08N5WRWNW",
    "marketplace": "amazon.de"
  }'
```

**Python**:

```python theme={null}
import requests

response = requests.post(
    "https://app.descripio.com/api/v1/reviews/refresh",
    headers={"Authorization": "Bearer dscr_abc123..."},
    json={
        "asin": "B08N5WRWNW",
        "marketplace": "amazon.de"
    }
)

if response.status_code == 202:
    job = response.json()
    print(f"Job ID: {job['jobId']}")
else:
    print(f"Error: {response.json()}")
```

**JavaScript**:

```javascript theme={null}
const response = await fetch(
  'https://app.descripio.com/api/v1/reviews/refresh',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer dscr_abc123...',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      asin: 'B08N5WRWNW',
      marketplace: 'amazon.de'
    })
  }
);

const job = await response.json();
console.log(`Job ID: ${job.jobId}`);
```

## Notes

* **Cooldown**: Each ASIN can only be refreshed once per 24 hours (Free tier). Paid plans have shorter cooldowns.
* **Caching**: Results are cached after job completion. Use `GET /reviews` to fetch without triggering a new job.
* **Concurrent jobs**: The number of jobs you can run simultaneously depends on your plan.


## OpenAPI

````yaml POST /api/v1/reviews/refresh
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/refresh:
    post:
      tags:
        - Reviews
      summary: Start a review refresh job
      operationId: refreshReviews
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshRequest'
            example:
              asin: B08N5WRWNW
              marketplace: amazon.de
      responses:
        '202':
          description: Job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshAcceptedResponse'
        '400':
          description: Invalid request (e.g. malformed ASIN)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid ASIN format (must be 10 alphanumeric characters)
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Monthly quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Monthly quota exceeded
                used: 100
                limit: 100
        '403':
          description: Marketplace not authorized for this store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Marketplace not authorized for this store
                hint: Configure marketplace access in your account settings
        '429':
          description: Rate limit, cooldown, or concurrency limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    RefreshRequest:
      type: object
      required:
        - asin
      properties:
        asin:
          type: string
          pattern: ^[A-Z0-9]{10}$
          example: B08N5WRWNW
        marketplace:
          type: string
          description: Optional. Defaults to `amazon.de` if omitted.
          example: amazon.de
    RefreshAcceptedResponse:
      type: object
      required:
        - jobId
        - asin
        - status
        - message
        - estimatedCompletionSeconds
      properties:
        jobId:
          type: integer
          example: 2877
        asin:
          type: string
          example: B08N5WRWNW
        status:
          type: string
          enum:
            - queued
          example: queued
        message:
          type: string
          example: Review refresh job created successfully
        estimatedCompletionSeconds:
          type: integer
          example: 60
    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
  securitySchemes:
    BearerApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key passed in Authorization header as Bearer token.

````