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
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
- Accept your job immediately (HTTP 202)
- Process it in the background
- 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:
Breaking changes will be introduced in new versions (e.g., /api/v2/).
