Skip to main content

​
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

EndpointMethodDescription
/reviews/refreshPOSTTrigger review scraping
/jobs/:jobIdGETCheck job status
/reviewsGETFetch cached reviews

​
Rate Limits

PlanRefresh Jobs/MonthRate LimitConcurrent Jobs
Free101/min1
Starter1002/min2
Pro5005/min5
Business2,00010/min10
Important: Only POST /reviews/refresh counts toward your quota. GET requests are free and unlimited.

​
HTTP Status Codes

CodeMeaning
200Success
202Job accepted (async processing started)
400Bad request (invalid parameters)
401Unauthorized (invalid or missing API key)
402Payment required (monthly quota exceeded)
403Forbidden (marketplace not authorized)
404Not found (job or cached data not found)
429Rate limit exceeded
500Internal 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/).