{"openapi":"3.1.0","info":{"title":"Screaming Data API","description":"Structured product data from 12 Amazon marketplaces — title, byline, variants, price, Best Sellers Rank with category ranks, rating and every product detail of any ASIN — as queued tasks, live, as history and through monitoring. One REST API; access and rates on request.\n\n**Authentication.** HTTP Basic with your API login and API key (`Authorization: Basic base64(login:api_key)`), or `Authorization: Bearer <api_key>`.\n\n**Requests and responses.** POST bodies are JSON arrays of task objects (up to 100 per request). Every response is an envelope with `status_code`, `status_message`, `cost` (USD) and a `tasks` array; each task carries its own `status_code`, `cost`, `data` (your input) and `result`. The list of status codes is served by `GET /v1/appendix/errors`. A body larger than 1048576 bytes is refused with HTTP 413 and a wrong HTTP method with HTTP 405 (both 40000).\n","contact":{"email":"support@screamingdata.dev"},"version":"1.0.0"},"servers":[{"url":"https://api.screamingdata.dev","description":"Production"},{"url":"/","description":"This server"}],"paths":{"/health":{"get":{"tags":["System"],"summary":"Liveness","description":"Liveness plus queue visibility. No authentication.","operationId":"system_health","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response System Health"}}}}}}},"/ready":{"get":{"tags":["System"],"summary":"Readiness","description":"200 when the database is reachable and all migrations are applied, else 503.","operationId":"system_ready","responses":{"200":{"description":"The database is reachable and every migration is applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadyDoc"}}}},"503":{"description":"Not ready: the database is unreachable or migrations are pending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadyDoc"}}}}}}},"/v1/public/access_request":{"post":{"tags":["Public"],"summary":"Request API access","description":"Stores a request for API access; an administrator turns it into an account and sends a\nsecure one-time link to the credentials. No authentication.\n\nErrors are request-level, so a form can rely on the HTTP status: invalid input → HTTP 400\nwith 40501 and the field name (or 40000 for a malformed body); more than 5 requests per hour\nfrom one IP address → HTTP 429 with 40202 and `Retry-After`.","operationId":"system_access_request","requestBody":{"description":"A JSON object (an array holding one object is accepted too).","content":{"application/json":{"schema":{"properties":{"email":{"type":"string","maxLength":254,"title":"Email","description":"Where we send the secure link to your API credentials."},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Name"},"company":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Company"},"use_case":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Use Case","description":"What you are building, expected volume, marketplaces."},"website":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Website","description":"Leave empty. Forms must render this field hidden (spam trap)."}},"type":"object","required":["email"]},"example":{"email":"dev@example.com","name":"Alex Doe","company":"Example Tools","use_case":"Daily BSR for 2,000 products on com and uk"}}},"required":true},"responses":{"200":{"description":"Envelope. Check `status_code` at the top level and in every task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"400":{"description":"Malformed request: 40000, 40001, 40501, 40502, 40503.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"429":{"description":"Rate limit exceeded (40202). See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"500":{"description":"Internal error (50000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"413":{"description":"Request body larger than 1048576 bytes (40000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}}}}},"/v1/amazon/product/task_post":{"post":{"tags":["Amazon Product"],"summary":"Post product tasks","description":"Creates one task per array element. Each task reads one product and is charged when it is\nposted (normal or high priority). If an observation younger than 60 minutes exists, the\ntask completes at once from it. Collect results with tasks_ready and task_get, or with\npostback / pingback webhooks. Results are kept 30 days.","operationId":"product_task_post","requestBody":{"description":"JSON array of task objects.","content":{"application/json":{"schema":{"items":{"properties":{"asin":{"type":"string","title":"Asin","description":"ASIN of the product. Case-insensitive; 10 letters or digits.","examples":["B0EXAMPLE1"]},"marketplace":{"type":"string","title":"Marketplace","description":"Marketplace code (`com`, `uk`, `de`, …); `us`, `usa` and `gb` are aliases.","examples":["com"]},"priority":{"type":"integer","enum":[1,2],"title":"Priority","description":"`1` normal, `2` high (processed first, costs more).","default":1},"tag":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Tag","description":"Your identifier, echoed in `data`, tasks_ready and pingbacks."},"postback_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Postback Url","description":"Receives the full task_get response (POST, signed) when the task is done."},"pingback_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Pingback Url","description":"Called with GET when the task is done; `$id` and `$tag` are replaced."}},"type":"object","required":["asin","marketplace"]},"type":"array","minItems":1,"maxItems":100},"example":[{"asin":"B0EXAMPLE1","marketplace":"com","priority":1,"tag":"catalog-sync"}]}},"required":true},"responses":{"200":{"description":"Envelope. Check `status_code` at the top level and in every task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"400":{"description":"Malformed request: 40000, 40001, 40501, 40502, 40503.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"401":{"description":"Authentication failed (40100), key revoked (40101), account disabled (40102).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"429":{"description":"Rate limit exceeded (40202). See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"500":{"description":"Internal error (50000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"402":{"description":"Payment required (40200): the balance does not cover any task of the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"413":{"description":"Request body larger than 1048576 bytes (40000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}}},"security":[{"basicAuth":[]},{"bearerAuth":[]}]}},"/v1/amazon/product/tasks_ready":{"get":{"tags":["Amazon Product"],"summary":"Completed tasks not collected yet","description":"Finished task_post tasks that have not been collected with task_get yet (at most 1,000,\noldest first). A task leaves the list once task_get returned it.","operationId":"product_tasks_ready","responses":{"200":{"description":"Envelope. Check `status_code` at the top level and in every task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"400":{"description":"Malformed request: 40000, 40001, 40501, 40502, 40503.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"401":{"description":"Authentication failed (40100), key revoked (40101), account disabled (40102).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"429":{"description":"Rate limit exceeded (40202). See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"500":{"description":"Internal error (50000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}}},"security":[{"basicAuth":[]},{"bearerAuth":[]}]}},"/v1/amazon/product/task_get/{id}":{"get":{"tags":["Amazon Product"],"summary":"Get a task result","description":"The product object of a task. The first call after completion marks the task collected.\nNot finished yet → task-level 40401; the product does not exist → task-level 40402 (not\ncharged); the source could not be read → task-level 50301 (not charged).","operationId":"product_task_get","security":[{"basicAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"Task id returned by task_post or tasks_ready.","title":"Id"},"description":"Task id returned by task_post or tasks_ready."}],"responses":{"200":{"description":"Envelope; `result` of a finished task holds product objects. Check `status_code` at the top level and in every task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductEnvelopeDoc"}}}},"400":{"description":"Malformed request: 40000, 40001, 40501, 40502, 40503.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"401":{"description":"Authentication failed (40100), key revoked (40101), account disabled (40102).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"429":{"description":"Rate limit exceeded (40202). See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"500":{"description":"Internal error (50000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"404":{"description":"Unknown task id (40400).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}}}}},"/v1/amazon/product/live":{"post":{"tags":["Amazon Product"],"summary":"Get product data live","description":"The product object in the same request. A stored observation younger than\n`max_age_minutes` is returned at once; otherwise the page is read within a 60-second budget.\nWhen the budget runs out the task returns 50301 and is not charged.","operationId":"product_live","requestBody":{"description":"JSON array with exactly one task.","content":{"application/json":{"schema":{"items":{"properties":{"asin":{"type":"string","title":"Asin","description":"ASIN of the product. Case-insensitive; 10 letters or digits.","examples":["B0EXAMPLE1"]},"marketplace":{"type":"string","title":"Marketplace","description":"Marketplace code (`com`, `uk`, `de`, …); `us`, `usa` and `gb` are aliases.","examples":["com"]},"max_age_minutes":{"type":"integer","maximum":43200.0,"minimum":0.0,"title":"Max Age Minutes","description":"Accept a stored observation up to this many minutes old; `0` always reads the page again.","default":60}},"type":"object","required":["asin","marketplace"]},"type":"array","maxItems":1,"minItems":1},"example":[{"asin":"B0EXAMPLE1","marketplace":"com","max_age_minutes":60}]}},"required":true},"responses":{"200":{"description":"Envelope; `result` of a finished task holds product objects. Check `status_code` at the top level and in every task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductEnvelopeDoc"}}}},"400":{"description":"Malformed request: 40000, 40001, 40501, 40502, 40503.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"401":{"description":"Authentication failed (40100), key revoked (40101), account disabled (40102).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"429":{"description":"Rate limit exceeded (40202). See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"500":{"description":"Internal error (50000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"402":{"description":"Payment required (40200): the balance does not cover any task of the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"413":{"description":"Request body larger than 1048576 bytes (40000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}}},"security":[{"basicAuth":[]},{"bearerAuth":[]}]}},"/v1/amazon/product/history":{"post":{"tags":["Amazon Product"],"summary":"Get product history","description":"Stored observations of a product, newest first — every observation, whichever request or\nsubscription produced it. Charged per element of the body (up to 1,000 rows each).","operationId":"product_history","requestBody":{"description":"JSON array of task objects.","content":{"application/json":{"schema":{"items":{"properties":{"asin":{"type":"string","title":"Asin","description":"ASIN of the product. Case-insensitive; 10 letters or digits.","examples":["B0EXAMPLE1"]},"marketplace":{"type":"string","title":"Marketplace","description":"Marketplace code (`com`, `uk`, `de`, …); `us`, `usa` and `gb` are aliases.","examples":["com"]},"date_from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date From","description":"First UTC day, YYYY-MM-DD."},"date_to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date To","description":"Last UTC day, YYYY-MM-DD."},"limit":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Limit","description":"Observations to return.","default":100},"offset":{"type":"integer","maximum":1000000.0,"minimum":0.0,"title":"Offset","description":"Observations to skip.","default":0}},"type":"object","required":["asin","marketplace"]},"type":"array","minItems":1,"maxItems":100},"example":[{"asin":"B0EXAMPLE1","marketplace":"com","date_from":"2026-09-01","date_to":"2026-09-24","limit":100,"offset":0}]}},"required":true},"responses":{"200":{"description":"Envelope; `result` of a finished task holds product objects. Check `status_code` at the top level and in every task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductEnvelopeDoc"}}}},"400":{"description":"Malformed request: 40000, 40001, 40501, 40502, 40503.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"401":{"description":"Authentication failed (40100), key revoked (40101), account disabled (40102).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"429":{"description":"Rate limit exceeded (40202). See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"500":{"description":"Internal error (50000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"402":{"description":"Payment required (40200): the balance does not cover any task of the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"413":{"description":"Request body larger than 1048576 bytes (40000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}}},"security":[{"basicAuth":[]},{"bearerAuth":[]}]}},"/v1/amazon/monitoring/add":{"post":{"tags":["Amazon Monitoring"],"summary":"Add products to monitoring","description":"Adds each product to monitoring: it is observed regularly at the chosen frequency. Adding\nthe same ASIN and marketplace again updates the frequency and tag of the existing\nsubscription. Adding is free; each delivered observation is charged at the monitoring\nprice. If the balance cannot cover an observation, the account's subscriptions switch to\n`paused_balance` and resume automatically after a top-up; a subscription added while the\nbalance is below the monitoring price (or while the account's subscriptions are paused)\nstarts `paused_balance`. An account can monitor up to 10,000 products.","operationId":"monitoring_add","requestBody":{"description":"JSON array of task objects.","content":{"application/json":{"schema":{"items":{"properties":{"asin":{"type":"string","title":"Asin","description":"ASIN of the product, 10 letters or digits.","examples":["B0EXAMPLE1"]},"marketplace":{"type":"string","title":"Marketplace","description":"Marketplace code; `us`, `usa` and `gb` are aliases.","examples":["com"]},"frequency":{"type":"string","enum":["hourly","every_6h","daily"],"title":"Frequency","description":"How often the product is observed and delivered."},"tag":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Tag","description":"Your identifier."},"external_user_id":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"External User Id","description":"Opaque id of your own end user. No personal data: e-mail addresses are rejected."}},"type":"object","required":["asin","marketplace","frequency"]},"type":"array","minItems":1,"maxItems":100},"example":[{"asin":"B0EXAMPLE1","marketplace":"com","frequency":"daily","tag":"client-42","external_user_id":"u_8f3a2c"}]}},"required":true},"responses":{"200":{"description":"Envelope; `result` holds subscription objects.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionEnvelopeDoc"}}}},"400":{"description":"Malformed request: 40000, 40001, 40501, 40502, 40503.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"401":{"description":"Authentication failed (40100), key revoked (40101), account disabled (40102).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"429":{"description":"Rate limit exceeded (40202). See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"500":{"description":"Internal error (50000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"413":{"description":"Request body larger than 1048576 bytes (40000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}}},"security":[{"basicAuth":[]},{"bearerAuth":[]}]}},"/v1/amazon/monitoring/delete":{"post":{"tags":["Amazon Monitoring"],"summary":"Delete monitored products","description":"Deletes subscriptions, each identified by `id` or by `asin` + `marketplace`. Observations\nalready delivered stay available in history. Unknown subscriptions → task-level 40400.","operationId":"monitoring_delete","requestBody":{"description":"JSON array of task objects.","content":{"application/json":{"schema":{"items":{"properties":{"id":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Id","description":"Subscription id."},"asin":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Asin","description":"ASIN, with `marketplace`, when `id` is not given."},"marketplace":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Marketplace","description":"Marketplace, with `asin`."}},"type":"object"},"type":"array","minItems":1,"maxItems":100},"example":[{"id":3051},{"asin":"B0EXAMPLE2","marketplace":"uk"}]}},"required":true},"responses":{"200":{"description":"Envelope. Check `status_code` at the top level and in every task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"400":{"description":"Malformed request: 40000, 40001, 40501, 40502, 40503.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"401":{"description":"Authentication failed (40100), key revoked (40101), account disabled (40102).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"429":{"description":"Rate limit exceeded (40202). See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"500":{"description":"Internal error (50000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"413":{"description":"Request body larger than 1048576 bytes (40000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}}},"security":[{"basicAuth":[]},{"bearerAuth":[]}]}},"/v1/amazon/monitoring/list":{"get":{"tags":["Amazon Monitoring"],"summary":"List monitored products","description":"Active and paused subscriptions, each with the latest observation delivered to it.","operationId":"monitoring_list","security":[{"basicAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Subscriptions to return.","default":100,"title":"Limit"},"description":"Subscriptions to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Subscriptions to skip.","default":0,"title":"Offset"},"description":"Subscriptions to skip."},{"name":"tag","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"description":"Only this tag.","title":"Tag"},"description":"Only this tag."}],"responses":{"200":{"description":"Envelope; `result` holds subscription objects.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionEnvelopeDoc"}}}},"400":{"description":"Malformed request: 40000, 40001, 40501, 40502, 40503.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"401":{"description":"Authentication failed (40100), key revoked (40101), account disabled (40102).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"429":{"description":"Rate limit exceeded (40202). See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"500":{"description":"Internal error (50000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}}}}},"/v1/appendix/user_data":{"get":{"tags":["Appendix"],"summary":"Account, balance, prices, usage and API keys","description":"Everything about the calling account: login, e-mail, balance (USD), plan, rate limits,\nthe price table (`rates`), usage today and this month, active API keys, and the secret used\nto sign webhooks.","operationId":"appendix_user_data","responses":{"200":{"description":"Envelope. Check `status_code` at the top level and in every task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"400":{"description":"Malformed request: 40000, 40001, 40501, 40502, 40503.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"401":{"description":"Authentication failed (40100), key revoked (40101), account disabled (40102).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"429":{"description":"Rate limit exceeded (40202). See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"500":{"description":"Internal error (50000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}}},"security":[{"basicAuth":[]},{"bearerAuth":[]}]}},"/v1/appendix/usage":{"get":{"tags":["Appendix"],"summary":"Usage per day and per endpoint","description":"Requests, tasks and cost per UTC day (days without usage included as zeros) and totals\nper endpoint. The range is at most 366 days.","operationId":"appendix_usage","security":[{"basicAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"First day, YYYY-MM-DD (UTC). Default: 29 days before date_to.","title":"Date From"},"description":"First day, YYYY-MM-DD (UTC). Default: 29 days before date_to."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Last day, YYYY-MM-DD (UTC). Default: today.","title":"Date To"},"description":"Last day, YYYY-MM-DD (UTC). Default: today."}],"responses":{"200":{"description":"Envelope. Check `status_code` at the top level and in every task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"400":{"description":"Malformed request: 40000, 40001, 40501, 40502, 40503.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"401":{"description":"Authentication failed (40100), key revoked (40101), account disabled (40102).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"429":{"description":"Rate limit exceeded (40202). See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"500":{"description":"Internal error (50000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}}}}},"/v1/appendix/marketplaces":{"get":{"tags":["Appendix"],"summary":"Supported Amazon marketplaces","description":"The 12 marketplaces with domain, currency and language. Codes are case-insensitive;\naliases (`us`, `usa` → `com`, `gb` → `uk`) are accepted wherever a marketplace is expected.","operationId":"appendix_marketplaces","responses":{"200":{"description":"Envelope. Check `status_code` at the top level and in every task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"400":{"description":"Malformed request: 40000, 40001, 40501, 40502, 40503.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"401":{"description":"Authentication failed (40100), key revoked (40101), account disabled (40102).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"429":{"description":"Rate limit exceeded (40202). See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"500":{"description":"Internal error (50000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}}},"security":[{"basicAuth":[]},{"bearerAuth":[]},{}]}},"/v1/appendix/status":{"get":{"tags":["Appendix"],"summary":"Availability per marketplace","description":"For every marketplace: `available` (null when there is not enough recent data),\n`status` (`operational`, `degraded`, `unavailable` or `unknown`), the success rate of source\nrequests over 24 hours, the median minutes from task_post to completion over 24 hours, and\nthe number of queued collection jobs. Aggregates only.","operationId":"appendix_status","responses":{"200":{"description":"Envelope. Check `status_code` at the top level and in every task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"400":{"description":"Malformed request: 40000, 40001, 40501, 40502, 40503.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"401":{"description":"Authentication failed (40100), key revoked (40101), account disabled (40102).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"429":{"description":"Rate limit exceeded (40202). See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"500":{"description":"Internal error (50000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}}},"security":[{"basicAuth":[]},{"bearerAuth":[]},{}]}},"/v1/appendix/errors":{"get":{"tags":["Appendix"],"summary":"Status codes","description":"Every status code the API returns, with its message, HTTP status and meaning.","operationId":"appendix_errors","responses":{"200":{"description":"Envelope. Check `status_code` at the top level and in every task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"400":{"description":"Malformed request: 40000, 40001, 40501, 40502, 40503.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"401":{"description":"Authentication failed (40100), key revoked (40101), account disabled (40102).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"429":{"description":"Rate limit exceeded (40202). See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"500":{"description":"Internal error (50000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}}},"security":[{"basicAuth":[]},{"bearerAuth":[]},{}]}},"/v1/appendix/keys":{"post":{"tags":["Appendix"],"summary":"Create API keys","description":"Creates one API key per task. The full key is in `result[0].key` of this response only:\nit is stored hashed and cannot be shown again.","operationId":"appendix_keys_create","requestBody":{"description":"One task per key to create.","content":{"application/json":{"schema":{"items":{"properties":{"label":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Label","description":"Your name for the key, e.g. `production`."}},"type":"object"},"type":"array","minItems":1,"maxItems":100},"example":[{"label":"production"}]}},"required":true},"responses":{"200":{"description":"Envelope. Check `status_code` at the top level and in every task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"400":{"description":"Malformed request: 40000, 40001, 40501, 40502, 40503.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"401":{"description":"Authentication failed (40100), key revoked (40101), account disabled (40102).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"429":{"description":"Rate limit exceeded (40202). See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"500":{"description":"Internal error (50000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"413":{"description":"Request body larger than 1048576 bytes (40000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}}},"security":[{"basicAuth":[]},{"bearerAuth":[]}]}},"/v1/appendix/keys/{key_id}":{"delete":{"tags":["Appendix"],"summary":"Revoke an API key","description":"Revokes the key; requests using it then fail with 40101. The key that authenticates this\nrequest can be revoked only while the account has another active key (40000 otherwise).\nAn id that is not one of the account's keys → 40400 (HTTP 404).","operationId":"appendix_keys_revoke","security":[{"basicAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"description":"`id` of the key (see user_data).","title":"Key Id"},"description":"`id` of the key (see user_data)."}],"responses":{"200":{"description":"Envelope. Check `status_code` at the top level and in every task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"400":{"description":"Malformed request: 40000, 40001, 40501, 40502, 40503.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"401":{"description":"Authentication failed (40100), key revoked (40101), account disabled (40102).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"429":{"description":"Rate limit exceeded (40202). See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"500":{"description":"Internal error (50000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}},"404":{"description":"No active or revoked key with this id belongs to the account (40400).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeDoc"}}}}}}}},"components":{"schemas":{"BsrDoc":{"properties":{"rank":{"type":"integer","title":"Rank","description":"Rank in the main category.","examples":[1432]},"category":{"type":"string","title":"Category","description":"Main category as the marketplace shows it.","examples":["Electronics"]},"subcategories":{"items":{"$ref":"#/components/schemas/CategoryRankDoc"},"type":"array","title":"Subcategories","description":"Ranks in subcategories."}},"type":"object","required":["rank","category","subcategories"],"title":"BsrDoc"},"CategoryRankDoc":{"properties":{"rank":{"type":"integer","title":"Rank","description":"Rank in this category.","examples":[12]},"category":{"type":"string","title":"Category","description":"Category name as the marketplace shows it.","examples":["Over-Ear Headphones"]}},"type":"object","required":["rank","category"],"title":"CategoryRankDoc"},"EnvelopeDoc":{"properties":{"version":{"type":"string","title":"Version","examples":["1.0.0"]},"status_code":{"type":"integer","title":"Status Code","examples":[20000]},"status_message":{"type":"string","title":"Status Message","examples":["Ok."]},"time":{"type":"string","title":"Time","examples":["0.0421 sec."]},"cost":{"type":"number","title":"Cost","description":"USD charged for the whole request.","examples":[0]},"tasks_count":{"type":"integer","title":"Tasks Count"},"tasks_error":{"type":"integer","title":"Tasks Error","description":"Tasks whose status_code is 40000 or above."},"tasks":{"items":{"$ref":"#/components/schemas/TaskDoc"},"type":"array","title":"Tasks"}},"type":"object","required":["version","status_code","status_message","time","cost","tasks_count","tasks_error","tasks"],"title":"EnvelopeDoc"},"PriceDoc":{"properties":{"amount":{"type":"number","title":"Amount","description":"Price in the marketplace currency.","examples":[59.99]},"currency":{"type":"string","title":"Currency","description":"ISO 4217 currency code.","examples":["USD"]}},"type":"object","required":["amount","currency"],"title":"PriceDoc"},"ProductDoc":{"properties":{"asin":{"type":"string","title":"Asin","description":"ASIN that was observed (uppercased).","examples":["B0EXAMPLE1"]},"marketplace":{"type":"string","title":"Marketplace","description":"Marketplace code.","examples":["com"]},"url":{"type":"string","title":"Url","description":"Product page URL on the marketplace.","examples":["https://www.amazon.com/dp/B0EXAMPLE1"]},"observed_at":{"type":"string","title":"Observed At","description":"When the page was read, ISO 8601 in UTC.","examples":["2026-09-24T12:37:52Z"]},"status":{"type":"string","enum":["ok","no_bsr","not_found"],"title":"Status","description":"`ok`; `no_bsr` — the page has no Best Sellers Rank; `not_found` — the product does not exist on this marketplace."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Product title as shown on the page."},"byline":{"items":{"type":"string"},"type":"array","title":"Byline","description":"Names shown under the title — usually the brand of the product.","examples":[["Acme"]]},"variant":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant","description":"Label of the selected variant (size, colour, style…).","examples":["Black"]},"variants":{"items":{"$ref":"#/components/schemas/VariantDoc"},"type":"array","title":"Variants","description":"Sibling variants listed on the page."},"price":{"anyOf":[{"$ref":"#/components/schemas/PriceDoc"},{"type":"null"}],"description":"Current price in the marketplace currency."},"bsr":{"anyOf":[{"$ref":"#/components/schemas/BsrDoc"},{"type":"null"}],"description":"Best Sellers Rank with the category ranks."},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating","description":"Average customer rating, 1.0 to 5.0.","examples":[4.5]},"ratings_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ratings Count","description":"Number of customer ratings.","examples":[2318]},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url","description":"URL of the main product image."},"details":{"additionalProperties":{"type":"string"},"type":"object","title":"Details","description":"Every label → value pair of the page's product details (the Best Sellers Rank and the rating aside). Keys are the labels lower-cased with runs of spaces and punctuation turned into `_`, in the marketplace's language (`item_weight`, `artikelgewicht`); values are the text as shown.","examples":[{"brand":"Acme","item_weight":"8.8 ounces"}]},"parser_version":{"type":"string","title":"Parser Version","description":"Version of the parser that produced the object.","examples":["2026.09.2"]}},"type":"object","required":["asin","marketplace","url","observed_at","status","title","byline","variant","variants","price","bsr","rating","ratings_count","image_url","details","parser_version"],"title":"ProductDoc","description":"One observation of a product page. A field that cannot be read reliably is null (empty\nfor lists and `details`) — values are never guessed."},"ProductEnvelopeDoc":{"properties":{"version":{"type":"string","title":"Version","examples":["1.0.0"]},"status_code":{"type":"integer","title":"Status Code","examples":[20000]},"status_message":{"type":"string","title":"Status Message","examples":["Ok."]},"time":{"type":"string","title":"Time","examples":["0.0421 sec."]},"cost":{"type":"number","title":"Cost","description":"USD charged for the whole request.","examples":[0]},"tasks_count":{"type":"integer","title":"Tasks Count"},"tasks_error":{"type":"integer","title":"Tasks Error","description":"Tasks whose status_code is 40000 or above."},"tasks":{"items":{"$ref":"#/components/schemas/ProductTaskDoc"},"type":"array","title":"Tasks"}},"type":"object","required":["version","status_code","status_message","time","cost","tasks_count","tasks_error","tasks"],"title":"ProductEnvelopeDoc"},"ProductTaskDoc":{"properties":{"id":{"type":"string","title":"Id","description":"UUID; the first 8 characters are the UTC MMDDHHmm of creation."},"status_code":{"type":"integer","title":"Status Code","examples":[20000]},"status_message":{"type":"string","title":"Status Message","examples":["Ok."]},"time":{"type":"string","title":"Time","examples":["0.0031 sec."]},"cost":{"type":"number","title":"Cost","description":"USD charged for this task.","examples":[0.0015]},"result_count":{"type":"integer","title":"Result Count"},"path":{"items":{"type":"string"},"type":"array","title":"Path","examples":[["v1","appendix","user_data"]]},"data":{"additionalProperties":true,"type":"object","title":"Data","description":"The task as received, plus `api` and `function`."},"result":{"anyOf":[{"items":{"$ref":"#/components/schemas/ProductDoc"},"type":"array"},{"type":"null"}],"title":"Result","description":"Product objects; null when the task failed or is not finished."}},"type":"object","required":["id","status_code","status_message","time","cost","result_count","path","data","result"],"title":"ProductTaskDoc"},"ReadyDoc":{"properties":{"status":{"type":"string","title":"Status","description":"`ready` or `not_ready`.","examples":["ready"]},"database":{"type":"boolean","title":"Database","description":"The database answered."},"pending_migrations":{"items":{"type":"string"},"type":"array","title":"Pending Migrations","description":"Migrations not applied yet."}},"type":"object","required":["status","database","pending_migrations"],"title":"ReadyDoc"},"SubscriptionDoc":{"properties":{"id":{"type":"integer","title":"Id","description":"Subscription id."},"asin":{"type":"string","title":"Asin","examples":["B0EXAMPLE1"]},"marketplace":{"type":"string","title":"Marketplace","examples":["com"]},"frequency":{"type":"string","enum":["hourly","every_6h","daily"],"title":"Frequency"},"tag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tag"},"external_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External User Id"},"status":{"type":"string","enum":["active","paused_balance"],"title":"Status"},"created_at":{"type":"string","title":"Created At","description":"ISO 8601 in UTC."},"latest_observation":{"anyOf":[{"$ref":"#/components/schemas/ProductDoc"},{"type":"null"}],"description":"The latest observation delivered to the subscription (monitoring/list only); null before the first delivery."}},"type":"object","required":["id","asin","marketplace","frequency","tag","external_user_id","status","created_at"],"title":"SubscriptionDoc"},"SubscriptionEnvelopeDoc":{"properties":{"version":{"type":"string","title":"Version","examples":["1.0.0"]},"status_code":{"type":"integer","title":"Status Code","examples":[20000]},"status_message":{"type":"string","title":"Status Message","examples":["Ok."]},"time":{"type":"string","title":"Time","examples":["0.0421 sec."]},"cost":{"type":"number","title":"Cost","description":"USD charged for the whole request.","examples":[0]},"tasks_count":{"type":"integer","title":"Tasks Count"},"tasks_error":{"type":"integer","title":"Tasks Error","description":"Tasks whose status_code is 40000 or above."},"tasks":{"items":{"$ref":"#/components/schemas/SubscriptionTaskDoc"},"type":"array","title":"Tasks"}},"type":"object","required":["version","status_code","status_message","time","cost","tasks_count","tasks_error","tasks"],"title":"SubscriptionEnvelopeDoc"},"SubscriptionTaskDoc":{"properties":{"id":{"type":"string","title":"Id","description":"UUID; the first 8 characters are the UTC MMDDHHmm of creation."},"status_code":{"type":"integer","title":"Status Code","examples":[20000]},"status_message":{"type":"string","title":"Status Message","examples":["Ok."]},"time":{"type":"string","title":"Time","examples":["0.0031 sec."]},"cost":{"type":"number","title":"Cost","description":"USD charged for this task.","examples":[0.0015]},"result_count":{"type":"integer","title":"Result Count"},"path":{"items":{"type":"string"},"type":"array","title":"Path","examples":[["v1","appendix","user_data"]]},"data":{"additionalProperties":true,"type":"object","title":"Data","description":"The task as received, plus `api` and `function`."},"result":{"anyOf":[{"items":{"$ref":"#/components/schemas/SubscriptionDoc"},"type":"array"},{"type":"null"}],"title":"Result","description":"Subscriptions."}},"type":"object","required":["id","status_code","status_message","time","cost","result_count","path","data","result"],"title":"SubscriptionTaskDoc"},"TaskDoc":{"properties":{"id":{"type":"string","title":"Id","description":"UUID; the first 8 characters are the UTC MMDDHHmm of creation."},"status_code":{"type":"integer","title":"Status Code","examples":[20000]},"status_message":{"type":"string","title":"Status Message","examples":["Ok."]},"time":{"type":"string","title":"Time","examples":["0.0031 sec."]},"cost":{"type":"number","title":"Cost","description":"USD charged for this task.","examples":[0.0015]},"result_count":{"type":"integer","title":"Result Count"},"path":{"items":{"type":"string"},"type":"array","title":"Path","examples":[["v1","appendix","user_data"]]},"data":{"additionalProperties":true,"type":"object","title":"Data","description":"The task as received, plus `api` and `function`."},"result":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Result","description":"Result objects; null when the task failed."}},"type":"object","required":["id","status_code","status_message","time","cost","result_count","path","data","result"],"title":"TaskDoc"},"VariantDoc":{"properties":{"name":{"type":"string","title":"Name","description":"Label of the variant as the page shows it.","examples":["White"]},"asin":{"type":"string","title":"Asin","description":"ASIN of the variant.","examples":["B0EXAMPLE2"]}},"type":"object","required":["name","asin"],"title":"VariantDoc"}},"securitySchemes":{"basicAuth":{"type":"http","description":"HTTP Basic with your API login and API key: `Authorization: Basic base64(login:api_key)`.","scheme":"basic"},"bearerAuth":{"type":"http","description":"`Authorization: Bearer <api_key>`; the key alone identifies the account.","scheme":"bearer","bearerFormat":"API key"}}},"tags":[{"name":"Amazon Product","description":"Title, byline, variants, price, Best Sellers Rank, rating and product details of any ASIN: task_post → tasks_ready → task_get, live, history."},{"name":"Amazon Monitoring","description":"Subscriptions: fresh observations hourly, every 6 hours or daily, charged per delivered observation."},{"name":"Appendix","description":"Account data, usage, keys, marketplaces, status codes."},{"name":"Public","description":"Endpoints that need no API key."},{"name":"System","description":"Liveness and readiness probes."}]}