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

# API Overview

> Understanding the async architecture

# API Overview

Descripio API uses an **async job-based architecture** to handle Amazon's rate limits gracefully.

## Architecture

```
POST /reviews/refresh  →  Job Created (queued)
         ↓
Poll GET /jobs/:id     →  Status: queued → processing → completed
         ↓
GET /reviews?asin=...  →  Cached reviews returned
```

**Why async?**

Scraping Amazon reviews takes 30-90 seconds. Instead of blocking your request, we:

1. Accept your job immediately (HTTP 202)
2. Process it in the background
3. Cache results for instant retrieval

## Base URL

```
https://app.descripio.com/api/v1
```

## Endpoints

| Endpoint           | Method | Description             |
| ------------------ | ------ | ----------------------- |
| `/reviews/refresh` | POST   | Trigger review scraping |
| `/jobs/:jobId`     | GET    | Check job status        |
| `/reviews`         | GET    | Fetch cached reviews    |

## Rate Limits

| Plan     | Refresh Jobs/Month | Rate Limit | Concurrent Jobs |
| -------- | ------------------ | ---------- | --------------- |
| Free     | 100                | 1/min      | 1               |
| Starter  | 1,000              | 10/min     | 2               |
| Pro      | 5,000              | 50/min     | 5               |
| Business | 30,000             | 200/min    | 10              |

> **Important**: Only POST `/reviews/refresh` counts toward your quota. GET requests are free and unlimited.

## HTTP Status Codes

| Code | Meaning                                   |
| ---- | ----------------------------------------- |
| 200  | Success                                   |
| 202  | Job accepted (async processing started)   |
| 400  | Bad request (invalid parameters)          |
| 401  | Unauthorized (invalid or missing API key) |
| 402  | Payment required (monthly quota exceeded) |
| 403  | Forbidden (marketplace not authorized)    |
| 404  | Not found (job or cached data not found)  |
| 429  | Rate limit exceeded                       |
| 500  | Internal server error                     |

## Content Type

All requests and responses use JSON:

```
Content-Type: application/json
```

## Versioning

The API is versioned via URL path:

```
/api/v1/...
```

Breaking changes will be introduced in new versions (e.g., `/api/v2/`).