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:

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:

/api/v1/...

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

Getting Started

API Reference

Guides

API Overview

API Overview

Architecture

Base URL

Endpoints

Rate Limits

HTTP Status Codes

Content Type

Versioning

​API Overview

​Architecture

​Base URL

​Endpoints

​Rate Limits

​HTTP Status Codes

​Content Type

​Versioning

API Overview

Architecture

Base URL

Endpoints

Rate Limits

HTTP Status Codes

Content Type

Versioning