{"openapi":"3.1.0","info":{"title":"Rewalto API","version":"0.157.0","summary":"India's data layer for AI agents and people","description":"One front door for people and agents: the site, the dashboards, the CLI and MCP all call this API. Every route is under `/v1`. Errors always have the same envelope (`ErrorEnvelope`); decide what to do from `error.retry`. Using the tools is free: credits are charged only for data actually delivered (C-012). Requests are rate limited per credential (or, without one, per IP) in one-minute windows: every answer carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`, and over the limit the answer is 429 `rate_limited` with `Retry-After`. A change that removes or alters something ships behind `/v2`.","x-rewalto-slice":"myntra"},"servers":[{"url":"https://api-dev.rewalto.com","description":"Staging, on the shared database (D-1360). API keys and Clerk sessions from the frontend dev issuer (D-1346); /v1/data is not served here until D-1391."},{"url":"https://api.rewalto.com","description":"Production. API keys and Clerk sessions from the production issuer."}],"tags":[{"name":"Coverage"},{"name":"Data"}],"paths":{"/v1/coverage/matrix":{"get":{"operationId":"getCoverageMatrix","summary":"Get which datasets Rewalto holds for each retailer","description":"For the API pages (issue #743): each retailer that holds at least one dataset sold through /v1/data, and for each of listings, price_history, search_rank, sponsored_share, delivery_eta, dark_stores, ratings and banners: whether Rewalto holds rows (held; null when it could not be read just now), the paid operation and path, how many rows with how that was found (rowsBasis counted: an exact count, for small tables and price readings from the hourly coverage summary; estimated: the database’s table statistics, with magnitude the power of ten to quote), the first and last IST day held, pin codes (price readings) or open stores (dark stores), and how many of its rows the free GET /v1/data/samples holds. Publish a retailer and dataset page only where held is true, and show a sample only where sampleRows is above 0. Read off the request path about hourly (generatedAt); answers 503 unavailable until the first read on a fresh server. Public and free.","tags":["Coverage"],"security":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CoverageMatrix"}}}},"429":{"description":"Error. The `error.code` is one of:\n- `rate_limited`: retry advice `after_reset`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimitHeader"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemainingHeader"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitResetHeader"},"Retry-After":{"$ref":"#/components/headers/RetryAfterHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error. The `error.code` is one of:\n- `internal`: retry advice `bounded`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error. The `error.code` is one of:\n- `unavailable`: retry advice `bounded`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/data/listings":{"get":{"operationId":"listListings","summary":"List retailer listings","description":"Retailer listings (what a retailer sells, as last seen), newest first, each with all its image URLs (primary first). With selection, exactly the listings chosen in a free preview (discoverListings), by their selectionIds. Charged 1 credit per 10 listings delivered, rounded up; re-reading the same listings within 7 days is free, and an empty page costs nothing. When the credits cannot cover the page: 402 credits_exhausted and no data.","tags":["Data"],"security":[{"sessionJwt":[]},{"apiKey":[]}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingsPage"}}}},"400":{"description":"Error. The `error.code` is one of:\n- `invalid_request`: retry advice `fix_request`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"invalid_request","status":400,"retry":"fix_request","message":"The request does not match the schema for this route","requestId":"req_0b8f6d3a-2c1e-4a79-9e5d-6f4a7c1b2d83","details":[{"path":"body/expiresInDays","message":"must be equal to one of the allowed values"}]}}}}},"401":{"description":"Error. The `error.code` is one of:\n- `key_expired`: retry advice `refresh_credentials`\n- `key_revoked`: retry advice `refresh_credentials`\n- `session_expired`: retry advice `refresh_credentials`\n- `unauthenticated`: retry advice `refresh_credentials`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"session_expired","status":401,"retry":"refresh_credentials","message":"The session token has expired; sign in again","requestId":"req_7c1e2a90-4b3d-4f6e-8a15-0d9c2b7e3f41"}}}}},"402":{"description":"Error. The `error.code` is one of:\n- `credits_exhausted`: retry advice `never`\n- `plan_required`: retry advice `never`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Error. The `error.code` is one of:\n- `org_missing`: retry advice `never`\n- `scope_missing`: retry advice `never`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Error. The `error.code` is one of:\n- `rate_limited`: retry advice `after_reset`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimitHeader"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemainingHeader"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitResetHeader"},"Retry-After":{"$ref":"#/components/headers/RetryAfterHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error. The `error.code` is one of:\n- `internal`: retry advice `bounded`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error. The `error.code` is one of:\n- `unavailable`: retry advice `bounded`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"retailer","in":"query","required":false,"schema":{"type":"string","title":"Retailer","examples":["blinkit"],"pattern":"^[a-z0-9_]{2,40}$"},"description":"Only this retailer (a key from /v1/data/retailers)."},{"name":"brand","in":"query","required":false,"schema":{"type":"string","title":"Brand","examples":["Aashirvaad"],"minLength":1,"maxLength":200},"description":"Only records with exactly this brand text, as the retailer wrote it (exact match, case-sensitive)."},{"name":"productId","in":"query","required":false,"schema":{"type":"string","title":"Product","examples":["0d6b4a52-4b6e-4c1a-9a7e-5b0d2f8f1a11"],"format":"uuid"},"description":"Only records matched to this Rewalto product id."},{"name":"retailerSku","in":"query","required":false,"schema":{"type":"string","title":"Retailer product id","examples":["prd-88213"],"minLength":1,"maxLength":200},"description":"Only this retailer product id (use together with retailer)."},{"name":"selection","in":"query","required":false,"schema":{"type":"string","title":"Selection","examples":["sel_7c1e5f0a2f554d2b8c360f3f1d9c2b77,sel_0d6b4a524b6e4c1a9a7e5b0d2f8f1a11"],"pattern":"^sel_[0-9a-f]{32}(,sel_[0-9a-f]{32}){0,99}$"},"description":"Only these listings: comma-separated selectionIds from the free preview (discoverListings), 1 to 100; a repeated id counts once. Charged like every listings page, for the listings delivered."},{"name":"limit","in":"query","required":false,"schema":{"type":"string","title":"Page size","examples":["100"],"pattern":"^[1-9][0-9]{0,2}$"},"description":"How many records to return, 1 to 500. Default 100."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","title":"Cursor","examples":["eyJ0IjoiMjAyNi0xMC0xNFQwOToyNzowMC4wMDBaIiwiaSI6NDgyMTAzNzcsImYiOiJhYmMxMjMifQ"],"pattern":"^[A-Za-z0-9_-]{1,600}$"},"description":"The nextCursor of the previous page, sent back with exactly the same filters. A cursor from other filters is refused."}]}},"/v1/data/observations":{"get":{"operationId":"listObservations","summary":"List price and availability history","description":"Price and availability history for listings, newest first. Charged 1 credit per 10 records delivered, rounded up; re-reading the same records within 7 days is free, and an empty page costs nothing. When the credits cannot cover the page: 402 credits_exhausted and no data.","tags":["Data"],"security":[{"sessionJwt":[]},{"apiKey":[]}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObservationsPage"}}}},"400":{"description":"Error. The `error.code` is one of:\n- `invalid_request`: retry advice `fix_request`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"invalid_request","status":400,"retry":"fix_request","message":"The request does not match the schema for this route","requestId":"req_0b8f6d3a-2c1e-4a79-9e5d-6f4a7c1b2d83","details":[{"path":"body/expiresInDays","message":"must be equal to one of the allowed values"}]}}}}},"401":{"description":"Error. The `error.code` is one of:\n- `key_expired`: retry advice `refresh_credentials`\n- `key_revoked`: retry advice `refresh_credentials`\n- `session_expired`: retry advice `refresh_credentials`\n- `unauthenticated`: retry advice `refresh_credentials`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"session_expired","status":401,"retry":"refresh_credentials","message":"The session token has expired; sign in again","requestId":"req_7c1e2a90-4b3d-4f6e-8a15-0d9c2b7e3f41"}}}}},"402":{"description":"Error. The `error.code` is one of:\n- `credits_exhausted`: retry advice `never`\n- `plan_required`: retry advice `never`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Error. The `error.code` is one of:\n- `org_missing`: retry advice `never`\n- `scope_missing`: retry advice `never`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Error. The `error.code` is one of:\n- `rate_limited`: retry advice `after_reset`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimitHeader"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemainingHeader"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitResetHeader"},"Retry-After":{"$ref":"#/components/headers/RetryAfterHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error. The `error.code` is one of:\n- `internal`: retry advice `bounded`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error. The `error.code` is one of:\n- `unavailable`: retry advice `bounded`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"retailer","in":"query","required":false,"schema":{"type":"string","title":"Retailer","examples":["blinkit"],"pattern":"^[a-z0-9_]{2,40}$"},"description":"Only this retailer (a key from /v1/data/retailers)."},{"name":"pincode","in":"query","required":false,"schema":{"type":"string","title":"Pin code","examples":["110092"],"pattern":"^(national|[0-9]{6})$"},"description":"Only readings for this six-digit pin code, or national for readings that are not pin-scoped."},{"name":"location","in":"query","required":false,"schema":{"type":"string","title":"Location","examples":["IN:city:karnataka:bengaluru"],"pattern":"^[A-Z]{2}:(pin:[1-9][0-9]{5}|city:[a-z0-9-]{1,100}:[a-z0-9-]{1,100}|area:[a-z0-9-]{1,100}:[a-z0-9-]{1,100}:[a-z0-9]{1,120}|store:[a-z0-9_]{2,40}:[A-Za-z0-9_-]{1,64})$"},"description":"A Core location id from the free lookup (GET /v1/data/locations, /cities or /stores): a pin, a city, an area or a dark store. It resolves to an explicit list of pin codes (see GET /v1/data/locations/filter). Never combine with pincode. More than one pin needs confirmPins. A store id (IN:store:<retailer>:<store id>) means the pin codes that dark store serves (its catchment as the sweeps saw it). Readings are kept per pin code, not per store, so it reads every kept reading at those pin codes, whichever store served them; no reading is attributed to the store itself."},{"name":"confirmPins","in":"query","required":false,"schema":{"type":"string","title":"Confirm pins","examples":["112"],"pattern":"^[1-9][0-9]{0,2}$"},"description":"Your consent to a multi-pin read: the number of pins the location resolves to, as GET /v1/data/locations/filter showed it. A different number is refused with the current count, so a place is never silently broadened."},{"name":"brand","in":"query","required":false,"schema":{"type":"string","title":"Brand","examples":["Aashirvaad"],"minLength":1,"maxLength":200},"description":"Only records with exactly this brand text, as the retailer wrote it (exact match, case-sensitive)."},{"name":"productId","in":"query","required":false,"schema":{"type":"string","title":"Product","examples":["0d6b4a52-4b6e-4c1a-9a7e-5b0d2f8f1a11"],"format":"uuid"},"description":"Only records matched to this Rewalto product id."},{"name":"retailerSku","in":"query","required":false,"schema":{"type":"string","title":"Retailer product id","examples":["prd-88213"],"minLength":1,"maxLength":200},"description":"Only this retailer product id (use together with retailer)."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time","title":"From","examples":["2026-10-01T00:00:00Z"]},"description":"Only readings at or after this time. Default: 30 days before now."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time","title":"To","examples":["2026-10-15T00:00:00Z"]},"description":"Only readings before this time. Default: now."},{"name":"limit","in":"query","required":false,"schema":{"type":"string","title":"Page size","examples":["100"],"pattern":"^[1-9][0-9]{0,2}$"},"description":"How many records to return, 1 to 500. Default 100."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","title":"Cursor","examples":["eyJ0IjoiMjAyNi0xMC0xNFQwOToyNzowMC4wMDBaIiwiaSI6NDgyMTAzNzcsImYiOiJhYmMxMjMifQ"],"pattern":"^[A-Za-z0-9_-]{1,600}$"},"description":"The nextCursor of the previous page, sent back with exactly the same filters. A cursor from other filters is refused."}]}},"/v1/data/ratings":{"get":{"operationId":"listRatingChanges","summary":"List rating changes per product and pin code","description":"For one retailer: each listing’s rating, rating count and review count on every IST day one of them changed, per pin code (or national), from that day’s newest reading, with the observation it came from. Newest day first, optionally one product (retailerSku), one pin code and a day range. Catalogue entry rr_rating_series; one record is one rating change. Charged per record delivered at the dataset’s published rate (GET /v1/catalogue/entries/{id} shows it); re-reading the same records within 7 days is free, and an empty page costs nothing. No quote is needed: meta.credits shows the rate charged and the credits left. When the credits cannot cover the page: 402 credits_exhausted and no data.","tags":["Data"],"security":[{"sessionJwt":[]},{"apiKey":[]}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RatingChangesPage"}}}},"400":{"description":"Error. The `error.code` is one of:\n- `invalid_request`: retry advice `fix_request`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"invalid_request","status":400,"retry":"fix_request","message":"The request does not match the schema for this route","requestId":"req_0b8f6d3a-2c1e-4a79-9e5d-6f4a7c1b2d83","details":[{"path":"body/expiresInDays","message":"must be equal to one of the allowed values"}]}}}}},"401":{"description":"Error. The `error.code` is one of:\n- `key_expired`: retry advice `refresh_credentials`\n- `key_revoked`: retry advice `refresh_credentials`\n- `session_expired`: retry advice `refresh_credentials`\n- `unauthenticated`: retry advice `refresh_credentials`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"session_expired","status":401,"retry":"refresh_credentials","message":"The session token has expired; sign in again","requestId":"req_7c1e2a90-4b3d-4f6e-8a15-0d9c2b7e3f41"}}}}},"402":{"description":"Error. The `error.code` is one of:\n- `credits_exhausted`: retry advice `never`\n- `plan_required`: retry advice `never`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Error. The `error.code` is one of:\n- `org_missing`: retry advice `never`\n- `scope_missing`: retry advice `never`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error. The `error.code` is one of:\n- `not_for_sale`: retry advice `never`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Error. The `error.code` is one of:\n- `rate_limited`: retry advice `after_reset`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimitHeader"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemainingHeader"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitResetHeader"},"Retry-After":{"$ref":"#/components/headers/RetryAfterHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error. The `error.code` is one of:\n- `internal`: retry advice `bounded`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error. The `error.code` is one of:\n- `unavailable`: retry advice `bounded`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"retailer","in":"query","required":true,"schema":{"type":"string","title":"Retailer","examples":["blinkit"],"pattern":"^[a-z0-9_]{2,40}$"},"description":"Only this retailer (a key from /v1/data/retailers)."},{"name":"retailerSku","in":"query","required":false,"schema":{"type":"string","title":"Retailer product id","examples":["prd-88213"],"minLength":1,"maxLength":200},"description":"Only this retailer product id (use together with retailer)."},{"name":"pincode","in":"query","required":false,"schema":{"type":"string","title":"Pin code","examples":["national"],"pattern":"^(national|[0-9]{6})$"},"description":"Only this six-digit pin code, or national."},{"name":"from","in":"query","required":false,"schema":{"type":"string","title":"From","examples":["2026-10-01"],"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"description":"Only IST days on or after this day (YYYY-MM-DD)."},{"name":"to","in":"query","required":false,"schema":{"type":"string","title":"To","examples":["2026-10-17"],"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"description":"Only IST days on or before this day (YYYY-MM-DD)."},{"name":"limit","in":"query","required":false,"schema":{"type":"string","title":"Page size","examples":["100"],"pattern":"^[1-9][0-9]{0,2}$"},"description":"How many records to return, 1 to 500. Default 100."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","title":"Cursor","examples":["eyJ0IjoiMjAyNi0xMC0xNFQwOToyNzowMC4wMDBaIiwiaSI6NDgyMTAzNzcsImYiOiJhYmMxMjMifQ"],"pattern":"^[A-Za-z0-9_-]{1,600}$"},"description":"The nextCursor of the previous page, sent back with exactly the same filters. A cursor from other filters is refused."}]}},"/v1/data/samples":{"get":{"operationId":"listDatasetSamples","summary":"Free real samples of each dataset","description":"Up to 12 real rows Rewalto keeps for each dataset sold through /v1/data, spread across apps (and cities for dark stores), each exactly a record of the paid read named, and every one at least 7 days old (D-1830 D-e; a dark store first seen, a storefront first crawled that long ago; the brand directory is reference data). Price history also holds each quick-commerce app's newest reading at up to 5 pin codes, one reading per pin code. Search rank is one quick-commerce search result page: the listings of one search term at one pin code on one IST day, best place first, each with its place, sponsored readings where the app marks ads, brand and read times. A listing carries its latest reading on or before that day (price, MRP, stock, pin code, read time), as searchListings include=latest delivers it. With offer (a GET /v1/price-list offerKey), only the samples that product is built from: quick-commerce listings for the quick-commerce catalogues, dark stores for the dark-store maps and reports, brands for the brand directory, storefronts for the D2C list, search results for share of search, and each report's listings, readings and ratings. Never made up (illustrative is always false): a dataset with nothing that old shows an empty list. Each entry names its paid operation, rate-card unit, published rate and catalogue entry. Public and free: no credential, nothing charged.","tags":["Data"],"security":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetSamples"}}}},"400":{"description":"Error. The `error.code` is one of:\n- `invalid_request`: retry advice `fix_request`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"invalid_request","status":400,"retry":"fix_request","message":"The request does not match the schema for this route","requestId":"req_0b8f6d3a-2c1e-4a79-9e5d-6f4a7c1b2d83","details":[{"path":"body/expiresInDays","message":"must be equal to one of the allowed values"}]}}}}},"429":{"description":"Error. The `error.code` is one of:\n- `rate_limited`: retry advice `after_reset`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimitHeader"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemainingHeader"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitResetHeader"},"Retry-After":{"$ref":"#/components/headers/RetryAfterHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error. The `error.code` is one of:\n- `internal`: retry advice `bounded`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error. The `error.code` is one of:\n- `unavailable`: retry advice `bounded`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"dataset","in":"query","required":false,"schema":{"type":"string","title":"Dataset","examples":["listings"],"pattern":"^(listings|price_history|mentions|ratings|banners|storefront_promos|promo_emails|ad_creatives|dark_stores|brand_directory|storefronts|search_rank|sponsored_share|delivery_eta)$"},"description":"Only this dataset: one of listings, price_history, mentions, ratings, banners, storefront_promos, promo_emails, ad_creatives, dark_stores, brand_directory, storefronts, search_rank, sponsored_share, delivery_eta."},{"name":"offer","in":"query","required":false,"schema":{"type":"string","title":"Product","examples":["pack_qc_catalogue_app"],"pattern":"^[a-z][a-z0-9_]{1,40}$"},"description":"Only the samples a price-list product (GET /v1/price-list offerKey) is built from: quick-commerce listings for the quick-commerce catalogues, dark stores for the dark-store maps and reports, brands for the brand directory, storefronts for the D2C list, and the listings, readings and ratings each report is built from. Cannot be combined with dataset."}]}},"/v1/data/search-ranks":{"get":{"operationId":"listSearchRanks","summary":"List search rank per product and search term","description":"For one retailer: on each IST day, for each search term and pin code (or national) Rewalto searched, where each listing ranked: its best place in the whole result list (ads included; null where the reply does not state where its page starts, beyond the first page), the first page and slot it was seen at, and how many replies showed it, placed it in places 1 to 10 and marked it sponsored. Observed, never a model. Newest day first, optionally one product (retailerSku), one search term, one pin code and a day range. Catalogue entries qc_rank_history and mp_rank_history; one record is one listing, term, pin and day. Charged per record delivered at the dataset’s published rate (GET /v1/catalogue/entries/{id} shows it); re-reading the same records within 7 days is free, and an empty page costs nothing. No quote is needed: meta.credits shows the rate charged and the credits left. When the credits cannot cover the page: 402 credits_exhausted and no data.","tags":["Data"],"security":[{"sessionJwt":[]},{"apiKey":[]}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRanksPage"}}}},"400":{"description":"Error. The `error.code` is one of:\n- `invalid_request`: retry advice `fix_request`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"invalid_request","status":400,"retry":"fix_request","message":"The request does not match the schema for this route","requestId":"req_0b8f6d3a-2c1e-4a79-9e5d-6f4a7c1b2d83","details":[{"path":"body/expiresInDays","message":"must be equal to one of the allowed values"}]}}}}},"401":{"description":"Error. The `error.code` is one of:\n- `key_expired`: retry advice `refresh_credentials`\n- `key_revoked`: retry advice `refresh_credentials`\n- `session_expired`: retry advice `refresh_credentials`\n- `unauthenticated`: retry advice `refresh_credentials`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"session_expired","status":401,"retry":"refresh_credentials","message":"The session token has expired; sign in again","requestId":"req_7c1e2a90-4b3d-4f6e-8a15-0d9c2b7e3f41"}}}}},"402":{"description":"Error. The `error.code` is one of:\n- `credits_exhausted`: retry advice `never`\n- `plan_required`: retry advice `never`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Error. The `error.code` is one of:\n- `org_missing`: retry advice `never`\n- `scope_missing`: retry advice `never`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error. The `error.code` is one of:\n- `not_for_sale`: retry advice `never`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Error. The `error.code` is one of:\n- `rate_limited`: retry advice `after_reset`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimitHeader"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemainingHeader"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitResetHeader"},"Retry-After":{"$ref":"#/components/headers/RetryAfterHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error. The `error.code` is one of:\n- `internal`: retry advice `bounded`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error. The `error.code` is one of:\n- `unavailable`: retry advice `bounded`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"retailer","in":"query","required":true,"schema":{"type":"string","title":"Retailer","examples":["blinkit"],"pattern":"^[a-z0-9_]{2,40}$"},"description":"The retailer (a key from /v1/data/retailers)."},{"name":"retailerSku","in":"query","required":false,"schema":{"type":"string","title":"Retailer product id","examples":["sku-123"],"minLength":1,"maxLength":200},"description":"Only this product (the retailer’s own id)."},{"name":"searchTerm","in":"query","required":false,"schema":{"type":"string","title":"Search term","examples":["shampoo"],"minLength":1,"maxLength":200},"description":"Only this search term (exact)."},{"name":"pincode","in":"query","required":false,"schema":{"type":"string","title":"Pin code","examples":["560034"],"pattern":"^(national|[0-9]{6})$"},"description":"Only this six-digit pin code, or national."},{"name":"from","in":"query","required":false,"schema":{"type":"string","title":"From","examples":["2026-10-01"],"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"description":"Only IST days on or after this day (YYYY-MM-DD)."},{"name":"to","in":"query","required":false,"schema":{"type":"string","title":"To","examples":["2026-10-17"],"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"description":"Only IST days on or before this day (YYYY-MM-DD)."},{"name":"limit","in":"query","required":false,"schema":{"type":"string","title":"Page size","examples":["100"],"pattern":"^[1-9][0-9]{0,2}$"},"description":"How many records to return, 1 to 500. Default 100."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","title":"Cursor","examples":["eyJ0IjoiMjAyNi0xMC0xNFQwOToyNzowMC4wMDBaIiwiaSI6NDgyMTAzNzcsImYiOiJhYmMxMjMifQ"],"pattern":"^[A-Za-z0-9_-]{1,600}$"},"description":"The nextCursor of the previous page, sent back with exactly the same filters. A cursor from other filters is refused."}]}},"/v1/data/sponsored-share":{"get":{"operationId":"listSponsoredShare","summary":"List sponsored share per brand and search term","description":"For one retailer: on each IST day, for each search term and pin code Rewalto searched, the product cards each brand held, how many were marked sponsored (in all and in places 1 to 10), and the brand’s share of all the sponsored cards of that term, pin and day. Ads are counted only from readings that can see the retailer’s ad marker (Blinkit, Zepto, Nykaa and Tata 1mg today); elsewhere the ad counts are 0 and the shares null. Observed counts, never a model. Newest day first, optionally one brand, one search term, one pin code and a day range. Catalogue entry lib_sponsored_share; one record is one brand, term, pin and day. Charged per record delivered at the dataset’s published rate (GET /v1/catalogue/entries/{id} shows it); re-reading the same records within 7 days is free, and an empty page costs nothing. No quote is needed: meta.credits shows the rate charged and the credits left. When the credits cannot cover the page: 402 credits_exhausted and no data.","tags":["Data"],"security":[{"sessionJwt":[]},{"apiKey":[]}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SponsoredSharePage"}}}},"400":{"description":"Error. The `error.code` is one of:\n- `invalid_request`: retry advice `fix_request`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"invalid_request","status":400,"retry":"fix_request","message":"The request does not match the schema for this route","requestId":"req_0b8f6d3a-2c1e-4a79-9e5d-6f4a7c1b2d83","details":[{"path":"body/expiresInDays","message":"must be equal to one of the allowed values"}]}}}}},"401":{"description":"Error. The `error.code` is one of:\n- `key_expired`: retry advice `refresh_credentials`\n- `key_revoked`: retry advice `refresh_credentials`\n- `session_expired`: retry advice `refresh_credentials`\n- `unauthenticated`: retry advice `refresh_credentials`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"session_expired","status":401,"retry":"refresh_credentials","message":"The session token has expired; sign in again","requestId":"req_7c1e2a90-4b3d-4f6e-8a15-0d9c2b7e3f41"}}}}},"402":{"description":"Error. The `error.code` is one of:\n- `credits_exhausted`: retry advice `never`\n- `plan_required`: retry advice `never`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Error. The `error.code` is one of:\n- `org_missing`: retry advice `never`\n- `scope_missing`: retry advice `never`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error. The `error.code` is one of:\n- `not_for_sale`: retry advice `never`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Error. The `error.code` is one of:\n- `rate_limited`: retry advice `after_reset`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimitHeader"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemainingHeader"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitResetHeader"},"Retry-After":{"$ref":"#/components/headers/RetryAfterHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error. The `error.code` is one of:\n- `internal`: retry advice `bounded`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error. The `error.code` is one of:\n- `unavailable`: retry advice `bounded`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestIdHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"retailer","in":"query","required":true,"schema":{"type":"string","title":"Retailer","examples":["blinkit"],"pattern":"^[a-z0-9_]{2,40}$"},"description":"The retailer (a key from /v1/data/retailers)."},{"name":"brand","in":"query","required":false,"schema":{"type":"string","title":"Brand","examples":["Mamaearth"],"minLength":1,"maxLength":200},"description":"Only this brand (exact match, case-sensitive)."},{"name":"searchTerm","in":"query","required":false,"schema":{"type":"string","title":"Search term","examples":["shampoo"],"minLength":1,"maxLength":200},"description":"Only this search term (exact)."},{"name":"pincode","in":"query","required":false,"schema":{"type":"string","title":"Pin code","examples":["560034"],"pattern":"^[0-9]{6}$"},"description":"Only this six-digit pin code."},{"name":"from","in":"query","required":false,"schema":{"type":"string","title":"From","examples":["2026-10-01"],"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"description":"Only IST days on or after this day (YYYY-MM-DD)."},{"name":"to","in":"query","required":false,"schema":{"type":"string","title":"To","examples":["2026-10-17"],"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},"description":"Only IST days on or before this day (YYYY-MM-DD)."},{"name":"limit","in":"query","required":false,"schema":{"type":"string","title":"Page size","examples":["100"],"pattern":"^[1-9][0-9]{0,2}$"},"description":"How many records to return, 1 to 500. Default 100."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","title":"Cursor","examples":["eyJ0IjoiMjAyNi0xMC0xNFQwOToyNzowMC4wMDBaIiwiaSI6NDgyMTAzNzcsImYiOiJhYmMxMjMifQ"],"pattern":"^[A-Za-z0-9_-]{1,600}$"},"description":"The nextCursor of the previous page, sent back with exactly the same filters. A cursor from other filters is refused."}]}}},"components":{"headers":{"RequestIdHeader":{"description":"The id of this request. Quote it when you report a problem. You may send your own `x-request-id` (8 to 128 plain characters); anything else is replaced.","schema":{"type":"string"}},"RateLimitLimitHeader":{"description":"Requests allowed in the current one-minute window for this credential (or, without one, this IP).","schema":{"type":"integer","minimum":1}},"RateLimitRemainingHeader":{"description":"Requests left in the current window.","schema":{"type":"integer","minimum":0}},"RateLimitResetHeader":{"description":"Seconds until the current window resets.","schema":{"type":"integer","minimum":1}},"RetryAfterHeader":{"description":"On a 429: seconds to wait before retrying (the same as `RateLimit-Reset`).","schema":{"type":"integer","minimum":1}}},"schemas":{"CoverageMatrix":{"type":"object","title":"Coverage matrix","description":"For each retailer and dataset sold through /v1/data, whether Rewalto holds rows and how many (issue #743). Free.","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"type":"object","title":"Matrix","description":"The retailers with at least one dataset held, and when it was read.","additionalProperties":false,"required":["generatedAt","retailers"],"properties":{"generatedAt":{"type":"string","format":"date-time","title":"Generated at","description":"When the matrix was read from the Library (UTC). It is read off the request path and kept for about an hour.","examples":["2026-11-01T14:00:00.000Z"]},"retailers":{"type":"array","title":"Retailers","description":"Each retailer that holds at least one dataset (or could not be read just now), by slug.","items":{"type":"object","title":"Retailer","description":"One retailer and its datasets.","additionalProperties":false,"required":["retailer","name","kind","datasets"],"properties":{"retailer":{"type":"string","title":"Retailer","description":"The retailer slug, as the data reads take it.","examples":["blinkit"]},"name":{"type":"string","title":"Name","description":"Its display name.","examples":["Blinkit"]},"kind":{"type":"string","title":"Kind","description":"Its kind (quick_commerce, marketplace, ...).","examples":["quick_commerce"]},"datasets":{"type":"array","title":"Datasets","description":"One cell per dataset, in a fixed order: listings, price_history, search_rank, sponsored_share, delivery_eta, dark_stores, ratings, banners.","items":{"type":"object","title":"Cell","description":"One retailer and dataset.","additionalProperties":false,"required":["dataset","operationId","path","held","rows","rowsBasis","magnitude","firstDay","lastDay","pincodes","stores","sampleRows"],"properties":{"dataset":{"type":"string","enum":["listings","price_history","search_rank","sponsored_share","delivery_eta","dark_stores","ratings","banners"],"title":"Dataset","description":"The dataset (as GET /v1/data/samples names it).","examples":["listings"]},"operationId":{"type":"string","title":"Operation","description":"The paid read that delivers it.","examples":["listListings"]},"path":{"type":"string","title":"Path","description":"Its path.","examples":["/v1/data/listings"]},"held":{"type":["null","boolean"],"title":"Held","description":"True when Rewalto holds at least one row of this dataset for the retailer; false when none; null when it could not be read just now (ask again later). Publish a page only for true.","examples":[true]},"rows":{"type":["null","integer"],"minimum":0,"title":"Rows","description":"How many rows Rewalto holds (see rowsBasis); null when not known.","examples":[34037]},"rowsBasis":{"type":["null","string"],"enum":["counted","estimated",null],"title":"Rows basis","description":"counted: an exact count (small tables, and price readings from the hourly coverage summary); estimated: the database’s own table statistics, good to an order of magnitude. Null with rows.","examples":["estimated"]},"magnitude":{"type":["null","integer"],"minimum":0,"title":"Magnitude","description":"The power of ten at or below rows (1, 10, 100, ...); quote this, not rows, when rowsBasis is estimated.","examples":[10000]},"firstDay":{"type":["null","string"],"format":"date","title":"First day","description":"The first IST day held; null when none or unknown.","examples":["2026-01-26"]},"lastDay":{"type":["null","string"],"format":"date","title":"Last day","description":"The last IST day held (the last read).","examples":["2026-11-01"]},"pincodes":{"type":["null","integer"],"minimum":0,"title":"Pin codes","description":"Pin codes the retailer’s price readings hold (price_history only); else null.","examples":[1180]},"stores":{"type":["null","integer"],"minimum":0,"title":"Stores","description":"Open dark stores on record (dark_stores only); else null.","examples":[1742]},"sampleRows":{"type":"integer","minimum":0,"title":"Sample rows","description":"Rows of this retailer in the free GET /v1/data/samples entry of the dataset (each at least 7 days old).","examples":[2]}}}}}}}}},"meta":{"type":"object","title":"Meta","description":"The (zero) charge.","additionalProperties":false,"required":["credits"],"properties":{"credits":{"$ref":"#/components/schemas/NoCharge"}}}}},"ErrorEnvelope":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","status","retry","message","requestId"],"properties":{"code":{"type":"string","enum":["invalid_request","invalid_json","unauthenticated","session_expired","key_expired","key_revoked","credits_exhausted","over_quote","plan_required","preview_needs_approval","price_changed","forbidden","org_missing","scope_missing","not_entitled","private_data","access_control","not_found","quote_expired","quote_already_approved","refund_refused","catalogue_refused","not_for_sale","export_not_ready","download_expired","reopen_expired","idempotency_conflict","stale_version","package_not_ready","upload_not_ready","cost_changed","billing_profile_missing","export_not_available","unknown_capability","schema_retired","payload_too_large","unsupported_media_type","rate_limited","internal","evidence_unavailable","payment_provider_unavailable","checkout_unavailable","invoicing_unavailable","provider_access_pending","connection_revoked","owner_required","provider_quota_exhausted","workspace_closed","unavailable"]},"status":{"type":"integer"},"retry":{"type":"string","enum":["fix_request","refresh_credentials","never","after_reset","bounded"]},"message":{"type":"string"},"requestId":{"type":"string"},"quote":{"$ref":"#/components/schemas/Quote"},"details":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"ListingsPage":{"type":"object","title":"Listings page","description":"One page of records with paging, the as-of time and what the page cost.","additionalProperties":false,"required":["data","page","meta"],"properties":{"data":{"type":"array","title":"Records","description":"The records of this page, newest first.","items":{"$ref":"#/components/schemas/Listing"}},"page":{"type":"object","title":"Page","description":"Paging state.","additionalProperties":false,"required":["limit","nextCursor"],"properties":{"limit":{"type":"integer","title":"Limit","description":"The page size used.","examples":[100]},"nextCursor":{"type":["null","string"],"title":"Next cursor","description":"Opaque. Send it back as cursor, with the same filters, for the next page; null on the last page.","examples":["eyJ0IjoiMjAyNi0xMC0xNFQwOToyNzowMC4wMDBaIiwiaSI6NDgyMTAzNzcsImYiOiJhYmMxMjMifQ"]}}},"meta":{"type":"object","title":"Meta","description":"Where the data comes from and what the page cost.","additionalProperties":false,"required":["kind","asOf","credits"],"properties":{"kind":{"type":"string","enum":["kept"],"title":"Kind","description":"kept: read from data Rewalto stores as history.","examples":["kept"]},"asOf":{"type":["null","string"],"format":"date-time","title":"As of","description":"The newest ingestion time among the records; null for an empty page.","examples":["2026-10-14T10:40:00Z"]},"credits":{"$ref":"#/components/schemas/ReadCredits"}}}}},"ObservationsPage":{"type":"object","title":"Observations page","description":"One page of records with paging, the as-of time and what the page cost.","additionalProperties":false,"required":["data","page","meta"],"properties":{"data":{"type":"array","title":"Records","description":"The records of this page, newest first.","items":{"$ref":"#/components/schemas/Observation"}},"page":{"type":"object","title":"Page","description":"Paging state.","additionalProperties":false,"required":["limit","nextCursor"],"properties":{"limit":{"type":"integer","title":"Limit","description":"The page size used.","examples":[100]},"nextCursor":{"type":["null","string"],"title":"Next cursor","description":"Opaque. Send it back as cursor, with the same filters, for the next page; null on the last page.","examples":["eyJ0IjoiMjAyNi0xMC0xNFQwOToyNzowMC4wMDBaIiwiaSI6NDgyMTAzNzcsImYiOiJhYmMxMjMifQ"]}}},"meta":{"type":"object","title":"Meta","description":"Where the data comes from and what the page cost.","additionalProperties":false,"required":["kind","asOf","credits"],"properties":{"kind":{"type":"string","enum":["kept"],"title":"Kind","description":"kept: read from data Rewalto stores as history.","examples":["kept"]},"asOf":{"type":["null","string"],"format":"date-time","title":"As of","description":"The newest ingestion time among the records; null for an empty page.","examples":["2026-10-14T10:40:00Z"]},"credits":{"$ref":"#/components/schemas/ReadCredits"}}}}},"RatingChangesPage":{"type":"object","title":"Rating changes page","description":"One page of records with paging, the as-of time and what the page cost.","additionalProperties":false,"required":["data","page","meta"],"properties":{"data":{"type":"array","title":"Records","description":"The records of this page, newest first.","items":{"$ref":"#/components/schemas/RatingChange"}},"page":{"type":"object","title":"Page","description":"Paging state.","additionalProperties":false,"required":["limit","nextCursor"],"properties":{"limit":{"type":"integer","title":"Limit","description":"The page size used.","examples":[100]},"nextCursor":{"type":["null","string"],"title":"Next cursor","description":"Opaque. Send it back as cursor, with the same filters, for the next page; null on the last page.","examples":["eyJ0IjoiMjAyNi0xMC0xNFQwOToyNzowMC4wMDBaIiwiaSI6NDgyMTAzNzcsImYiOiJhYmMxMjMifQ"]}}},"meta":{"type":"object","title":"Meta","description":"Where the data comes from and what the page cost.","additionalProperties":false,"required":["kind","asOf","credits"],"properties":{"kind":{"type":"string","enum":["kept"],"title":"Kind","description":"kept: read from data Rewalto stores as history.","examples":["kept"]},"asOf":{"type":["null","string"],"format":"date-time","title":"As of","description":"The newest ingestion time among the records; null for an empty page.","examples":["2026-10-14T10:40:00Z"]},"credits":{"$ref":"#/components/schemas/ReadCredits"}}}}},"DatasetSamples":{"type":"object","title":"Dataset samples","description":"Free real samples, one entry per dataset (D-1830 D-e).","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"type":"array","title":"Datasets","description":"One entry per dataset, in a fixed order.","items":{"$ref":"#/components/schemas/DatasetSample"}},"meta":{"type":"object","title":"Meta","description":"How the samples were chosen; free.","additionalProperties":false,"required":["rowsPerDataset","minAgeDays","illustrative","credits","offer","generatedAt"],"properties":{"rowsPerDataset":{"type":"integer","title":"Rows per dataset","description":"The most rows per dataset; price history adds up to 5 per quick-commerce app.","examples":[12]},"minAgeDays":{"type":"integer","title":"Minimum age","description":"Every row is at least this many days old.","examples":[7]},"illustrative":{"const":false,"title":"Illustrative","description":"Always false: real kept rows, never made up.","examples":[false]},"credits":{"$ref":"#/components/schemas/NoCharge"},"offer":{"type":["null","string"],"title":"Product","description":"The price-list product (offerKey) the samples match, when one was asked for; else null.","examples":["pack_qc_catalogue_app"]},"generatedAt":{"type":["null","string"],"format":"date-time","title":"Generated at","description":"The oldest generatedAt of the entries: every row was read at or after it (UTC). Null when none could be read.","examples":["2026-11-01T14:00:00.000Z"]}}}}},"SearchRanksPage":{"type":"object","title":"Search ranks page","description":"One page of records with paging, the as-of time and what the page cost.","additionalProperties":false,"required":["data","page","meta"],"properties":{"data":{"type":"array","title":"Records","description":"The records of this page, newest first.","items":{"$ref":"#/components/schemas/SearchRank"}},"page":{"type":"object","title":"Page","description":"Paging state.","additionalProperties":false,"required":["limit","nextCursor"],"properties":{"limit":{"type":"integer","title":"Limit","description":"The page size used.","examples":[100]},"nextCursor":{"type":["null","string"],"title":"Next cursor","description":"Opaque. Send it back as cursor, with the same filters, for the next page; null on the last page.","examples":["eyJ0IjoiMjAyNi0xMC0xNFQwOToyNzowMC4wMDBaIiwiaSI6NDgyMTAzNzcsImYiOiJhYmMxMjMifQ"]}}},"meta":{"type":"object","title":"Meta","description":"Where the data comes from and what the page cost.","additionalProperties":false,"required":["kind","asOf","credits"],"properties":{"kind":{"type":"string","enum":["kept"],"title":"Kind","description":"kept: read from data Rewalto stores as history.","examples":["kept"]},"asOf":{"type":["null","string"],"format":"date-time","title":"As of","description":"The newest ingestion time among the records; null for an empty page.","examples":["2026-10-14T10:40:00Z"]},"credits":{"$ref":"#/components/schemas/ReadCredits"}}}}},"SponsoredSharePage":{"type":"object","title":"Sponsored share page","description":"One page of records with paging, the as-of time and what the page cost.","additionalProperties":false,"required":["data","page","meta"],"properties":{"data":{"type":"array","title":"Records","description":"The records of this page, newest first.","items":{"$ref":"#/components/schemas/SponsoredShareCell"}},"page":{"type":"object","title":"Page","description":"Paging state.","additionalProperties":false,"required":["limit","nextCursor"],"properties":{"limit":{"type":"integer","title":"Limit","description":"The page size used.","examples":[100]},"nextCursor":{"type":["null","string"],"title":"Next cursor","description":"Opaque. Send it back as cursor, with the same filters, for the next page; null on the last page.","examples":["eyJ0IjoiMjAyNi0xMC0xNFQwOToyNzowMC4wMDBaIiwiaSI6NDgyMTAzNzcsImYiOiJhYmMxMjMifQ"]}}},"meta":{"type":"object","title":"Meta","description":"Where the data comes from and what the page cost.","additionalProperties":false,"required":["kind","asOf","credits"],"properties":{"kind":{"type":"string","enum":["kept"],"title":"Kind","description":"kept: read from data Rewalto stores as history.","examples":["kept"]},"asOf":{"type":["null","string"],"format":"date-time","title":"As of","description":"The newest ingestion time among the records; null for an empty page.","examples":["2026-10-14T10:40:00Z"]},"credits":{"$ref":"#/components/schemas/ReadCredits"}}}}},"NoCharge":{"type":"object","title":"No charge","description":"Always nothing: discovery and samples are free and never touch the credit balance.","additionalProperties":false,"required":["charged","units","freeReread","rate"],"properties":{"charged":{"const":0,"title":"Credits charged","description":"Always 0.","examples":[0]},"units":{"const":0,"title":"Records delivered","description":"Always 0: previews and samples are not delivered data.","examples":[0]},"freeReread":{"const":false,"title":"Free re-read","description":"Always false.","examples":[false]},"rate":{"type":"null","title":"Published rate","description":"Always null: nothing is charged."}}},"Quote":{"title":"Quote","description":"What a run would cost at most. mode published: the recipe has a published rate and runs at once. mode approval: no rate is set yet, so the run starts only after the quote is approved. The ceiling is never exceeded; a run is charged for what it delivers, rounded up.","type":"object","additionalProperties":false,"required":["id","mode","status","recipe","unit","units","rateVersion","extras","lines","ceiling","expiresAt","createdAt","approvedAt","recurring"],"properties":{"id":{"type":"string","format":"uuid"},"mode":{"type":"string","enum":["published","approval"]},"status":{"type":"string","enum":["open","approved","expired"],"description":"open: can be approved. approved: credits are held. expired: ask for a new quote."},"recipe":{"type":"string"},"unit":{"type":"string"},"units":{"type":"integer","minimum":1,"description":"The units estimate this quote prices."},"rateVersion":{"type":"string","description":"The one rate version every line was priced at, for example c1.r2."},"extras":{"type":"array","items":{"title":"QuoteExtra","description":"An extra (a tool such as a browser or OCR) applied to the quoted data.","type":"object","additionalProperties":false,"required":["key","credits","perUnits","multiplier"],"properties":{"key":{"type":"string","description":"The extra’s name, from the rate card."},"credits":{"type":"integer","minimum":0,"description":"Credits per perUnits units."},"perUnits":{"type":"integer","minimum":1},"multiplier":{"type":"integer","minimum":1,"description":"How many times the extra applies per unit, for example the number of pin codes."}},"examples":[{"key":"browser","credits":1,"perUnits":1,"multiplier":1}]}},"lines":{"type":"array","items":{"title":"QuoteLine","description":"One kind of data in a quote: the units expected and the credits for them.","type":"object","additionalProperties":false,"required":["recipe","unit","units","base","extras","credits"],"properties":{"recipe":{"type":"string"},"unit":{"type":"string","description":"What one unit is, for example page or record."},"units":{"type":"integer","minimum":0},"base":{"type":"object","additionalProperties":false,"required":["credits","perUnits"],"properties":{"credits":{"type":"integer","minimum":0},"perUnits":{"type":"integer","minimum":1}}},"extras":{"type":"array","items":{"title":"QuoteExtra","description":"An extra (a tool such as a browser or OCR) applied to the quoted data.","type":"object","additionalProperties":false,"required":["key","credits","perUnits","multiplier"],"properties":{"key":{"type":"string","description":"The extra’s name, from the rate card."},"credits":{"type":"integer","minimum":0,"description":"Credits per perUnits units."},"perUnits":{"type":"integer","minimum":1},"multiplier":{"type":"integer","minimum":1,"description":"How many times the extra applies per unit, for example the number of pin codes."}},"examples":[{"key":"browser","credits":1,"perUnits":1,"multiplier":1}]}},"credits":{"type":"integer","minimum":0,"description":"Credits for this line, rounded up."}}}},"ceiling":{"type":"integer","minimum":0,"description":"The most the run can be charged, in credits. This is what approval holds."},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"approvedAt":{"type":["null","string"],"format":"date-time"},"run":{"title":"QuoteRun","description":"Only for a fresh-read run: what it reads. Its id is this quote’s id (GET /v1/runs/{id} once approved).","type":["null","object"],"additionalProperties":false,"required":["query","pincodes"],"properties":{"query":{"type":"string","minLength":1,"maxLength":200,"description":"A search term, or a product reference for a recipe that reads one product."},"pincodes":{"type":"array","minItems":1,"maxItems":20,"uniqueItems":true,"items":{"type":"string","pattern":"^([1-9][0-9]{5}|national)$"},"description":"Pin codes to read at; `national` for a recipe that is not location scoped. One job each."}}},"recurring":{"title":"QuoteRecurring","description":"Only for a recurring report or watch, shown once before the first delivery: the cost of each delivery and of a month, and whether the month fits the credits left.","type":["null","object"],"additionalProperties":false,"required":["cadence","deliveriesPerMonth","perDelivery","perMonth","creditsAvailable","fitsPlan","notice"],"properties":{"cadence":{"type":"string","enum":["daily","weekly","monthly"]},"deliveriesPerMonth":{"type":"integer","minimum":1,"description":"Deliveries counted in a month: the most the cadence can make."},"perDelivery":{"type":"integer","minimum":0,"description":"Credits for one delivery (at most)."},"perMonth":{"type":"integer","minimum":0,"description":"Credits for a month of deliveries (at most)."},"creditsAvailable":{"type":"integer","minimum":-1,"description":"Credits the organisation has now; -1 when it has unlimited credits (as `available` on GET /v1/credits/balance, contract 0.28.0)."},"fitsPlan":{"type":"boolean","description":"False when the month costs more than the credits left. Always true with unlimited credits."},"notice":{"type":["null","string"],"description":"When fitsPlan is false: that it will not fit and a bigger plan is needed."}}}},"examples":[{"id":"9b1d6e0a-4c3f-4f7e-8a21-5d0c7b9e1f42","mode":"published","status":"open","recipe":"commerce_product_page","unit":"page","units":120,"rateVersion":"c1.r1","extras":[{"key":"browser","credits":1,"perUnits":1,"multiplier":1}],"lines":[{"recipe":"commerce_product_page","unit":"page","units":120,"base":{"credits":1,"perUnits":1},"extras":[{"key":"browser","credits":1,"perUnits":1,"multiplier":1}],"credits":240}],"ceiling":240,"expiresAt":"2026-10-15T10:30:00.000Z","createdAt":"2026-10-15T10:00:00.000Z","approvedAt":null,"recurring":{"cadence":"weekly","deliveriesPerMonth":5,"perDelivery":240,"perMonth":1200,"creditsAvailable":1000,"fitsPlan":false,"notice":"A month of deliveries can cost up to 1200 credits and 1000 are left: it will not fit. A bigger plan is needed."}}]},"Listing":{"type":"object","title":"Listing","description":"One product as one retailer lists it, with when it was first and last seen.","additionalProperties":false,"required":["id","retailer","retailerSku","images","firstSeen","lastSeen","observations"],"properties":{"id":{"type":"string","format":"uuid","title":"Listing id","description":"Stable identifier of the listing.","examples":["7c1e5f0a-2f55-4d2b-8c36-0f3f1d9c2b77"]},"retailer":{"type":"string","title":"Retailer","description":"The retailer key.","examples":["nykaa"]},"retailerSku":{"type":"string","title":"Retailer product id","description":"The retailer own product identifier.","examples":["1234567"]},"title":{"type":["null","string"],"title":"Title","description":"The product title as the retailer showed it.","examples":["Maybelline Superstay Matte Ink"]},"brand":{"type":["null","string"],"title":"Brand","description":"The brand as the retailer attributed it.","examples":["Maybelline"]},"packSizeRaw":{"type":["null","string"],"title":"Pack size","description":"The pack size exactly as printed.","examples":["5 ml"]},"imageUrl":{"type":["null","string"],"title":"Image URL","description":"The primary product image address (not the image itself): the first of images.","examples":["https://images.example/lipstick-1.jpg"]},"images":{"type":"array","title":"Images","description":"Every image address the source showed, in its order, primary first. Empty when it showed none.","items":{"$ref":"#/components/schemas/ListingImage"}},"url":{"type":["null","string"],"title":"Product page","description":"The retailer product page.","examples":["https://www.nykaa.com/p/1234567"]},"productId":{"type":["null","string"],"format":"uuid","title":"Product id","description":"The matched Rewalto product, when matched.","examples":["0d6b4a52-4b6e-4c1a-9a7e-5b0d2f8f1a11"]},"firstSeen":{"type":"string","format":"date-time","title":"First seen","description":"When the listing was first observed.","examples":["2026-08-27T08:00:00Z"]},"lastSeen":{"type":"string","format":"date-time","title":"Last seen","description":"When the listing was last observed.","examples":["2026-10-14T09:00:00Z"]},"observations":{"type":"integer","title":"Observation count","description":"How many times the listing has been observed.","examples":[37]},"brandTag":{"type":["null","object"],"title":"Model brand tag","description":"Rewalto's model reading of the brand from the title (plan 13 T8), given only when the retailer attributed no brand. It never replaces brand. Null when the title is not tagged yet.","additionalProperties":false,"required":["brand","confidence","method","promptVersion","taggedAt","accuracy"],"properties":{"brand":{"type":["null","string"],"title":"Brand","description":"The brand span chosen from the title; null when the title names none or the model was below the minimum confidence (never a guess).","examples":["Bazana"]},"confidence":{"type":["null","number"],"minimum":0,"maximum":1,"title":"Confidence","description":"The model's own confidence, 0 to 1; a brand is kept only at 0.75 or above.","examples":[0.87]},"method":{"type":"string","enum":["model"],"title":"Method","description":"Always model: read by a language model, not the retailer.","examples":["model"]},"promptVersion":{"type":"string","title":"Prompt version","description":"The tagging prompt that produced it.","examples":["core-brand-v1"]},"taggedAt":{"type":"string","format":"date-time","title":"Tagged at","description":"When the title was tagged.","examples":["2026-10-16T11:40:20Z"]},"accuracy":{"type":"string","enum":["not_measured","measured"],"title":"Accuracy","description":"Whether this tag kind has been measured against hand-checked titles. not_measured: no accuracy figure yet; treat the tag as unverified.","examples":["not_measured"]}}},"categoryTag":{"type":["null","object"],"title":"Model category tag","description":"Rewalto's model reading of the GS1 GPC segment and family from the title (D-1498). Null when the title is not tagged yet.","additionalProperties":false,"required":["status","standard","gpcVersion","segment","family","method","promptVersion","taggedAt","accuracy"],"properties":{"status":{"type":"string","enum":["classified","segment_only","unclassified"],"title":"Status","description":"classified: segment and family chosen; segment_only: a segment without a family; unclassified: no GPC entry chosen (never a guess).","examples":["classified"]},"standard":{"type":"string","enum":["GS1 GPC"],"title":"Standard","description":"The classification: GS1 Global Product Classification.","examples":["GS1 GPC"]},"gpcVersion":{"type":"string","title":"GPC version","description":"The GS1 GPC publication used.","examples":["20260520"]},"segment":{"type":["null","object"],"title":"GS1 GPC entry","description":"A GS1 Global Product Classification code and its English title; null when not chosen.","additionalProperties":false,"required":["code","title"],"properties":{"code":{"type":"string","title":"Code","description":"The eight-digit GS1 GPC code.","examples":["50000000"]},"title":{"type":"string","title":"Title","description":"The GS1 GPC English title.","examples":["Food/Beverage"]}}},"family":{"type":["null","object"],"title":"GS1 GPC entry","description":"A GS1 Global Product Classification code and its English title; null when not chosen.","additionalProperties":false,"required":["code","title"],"properties":{"code":{"type":"string","title":"Code","description":"The eight-digit GS1 GPC code.","examples":["50000000"]},"title":{"type":"string","title":"Title","description":"The GS1 GPC English title.","examples":["Food/Beverage"]}}},"method":{"type":"string","enum":["model"],"title":"Method","description":"Always model: read by a language model, not the retailer.","examples":["model"]},"promptVersion":{"type":"string","title":"Prompt version","description":"The tagging prompt that produced it.","examples":["core-category-gpc-v1"]},"taggedAt":{"type":"string","format":"date-time","title":"Tagged at","description":"When the title was tagged.","examples":["2026-10-17T00:10:00Z"]},"accuracy":{"type":"string","enum":["not_measured","measured"],"title":"Accuracy","description":"Whether this tag kind has been measured against hand-checked titles. not_measured: no accuracy figure yet; treat the tag as unverified.","examples":["not_measured"]}}},"similarity":{"type":"number","minimum":-1,"maximum":1,"title":"Similarity","description":"Listing search with mode=semantic only: the cosine similarity of the listing and the query embeddings (OpenAI text-embedding-3-small, 512 dimensions), -1 to 1, higher is closer in meaning, to 6 decimal places. Absent everywhere else.","examples":[0.71234]},"match":{"type":"object","title":"Search match","description":"How this listing matched the search, only on search results. kind: exact_id (the query is the retailer product id), phrase (the name holds the words in order, next to each other), words (every word, spread out), brand (only the brand the query names), near (an approximate match, a likely misspelling). wholeWords of queryWords are whole words of the listing (\"butter\" in \"Amul Butter\", not in \"Buttermilk\"); allWords is true when every word is. When any listing holds every word as a whole word, the search returns only such listings.","additionalProperties":false,"required":["kind","wholeWords","queryWords","allWords"],"properties":{"kind":{"type":"string","enum":["exact_id","phrase","words","brand","near"],"title":"Kind","description":"How the listing matched.","examples":["phrase"]},"wholeWords":{"type":"integer","title":"Whole words","description":"How many words of the query are whole words of the listing.","examples":[2]},"queryWords":{"type":"integer","title":"Query words","description":"How many words the query has (at most 8).","examples":[2]},"allWords":{"type":"boolean","title":"All words whole","description":"Every word of the query is a whole word of the listing.","examples":[true]}}},"latest":{"type":"object","title":"Newest price reading","description":"The listing's newest kept reading in the last 30 days, at the pin code asked for, else at any pin. Never a guess.","additionalProperties":false,"required":["state","priceMinor","mrpMinor","currency","inStock","pincode","observedAt"],"properties":{"state":{"type":"string","enum":["priced","no_price_shown","no_recent_reading","excluded_pin_day"],"title":"State","description":"priced: the reading shows a price. no_price_shown: the newest reading had none. no_recent_reading: no kept reading in the last 30 days (at the pin, when one was asked for). excluded_pin_day: the newest reading falls on a pin-day left out of the data (D-1458), so nothing is shown.","examples":["priced"]},"priceMinor":{"type":["null","integer"],"title":"Price","description":"Selling price in paise; null when not shown.","examples":[5600]},"mrpMinor":{"type":["null","integer"],"title":"MRP","description":"MRP in paise; null when not shown.","examples":[6000]},"currency":{"const":"INR","title":"Currency","description":"Always INR.","examples":["INR"]},"inStock":{"type":["null","boolean"],"title":"In stock","description":"In stock in that reading; null when the retailer does not say (always null for Flipkart).","examples":[true]},"pincode":{"type":["null","string"],"title":"Pin code","description":"Where the reading was taken.","examples":["110092"]},"observedAt":{"type":["null","string"],"format":"date-time","title":"Read at","description":"When the reading was taken; null when there is none.","examples":["2026-10-20T05:55:00Z"]}}}}},"ReadCredits":{"type":"object","title":"Credits","description":"What this response cost, at the published rate. An empty page, a free re-read of identical data and a plain list cost nothing.","additionalProperties":false,"required":["charged","units","freeReread","rate"],"properties":{"charged":{"type":"integer","title":"Credits charged","description":"Credits taken from the balance for this response.","examples":[10],"minimum":0},"units":{"type":"integer","title":"Records delivered","description":"How many records are in data.","examples":[100],"minimum":0},"freeReread":{"type":"boolean","title":"Free re-read","description":"True when identical data was read within 7 days and is not charged again.","examples":[false]},"rate":{"type":["null","object"],"title":"Published rate","description":"Credits per number of records, and the rate version; null when nothing is charged for this list.","additionalProperties":false,"required":["credits","perUnits","version"],"properties":{"credits":{"type":"integer","title":"Credits","description":"Credits charged for every perUnits records.","examples":[1]},"perUnits":{"type":"integer","title":"Per units","description":"Number of records the credits cover.","examples":[10]},"version":{"type":"string","title":"Rate version","description":"The rate card the price came from.","examples":["card-1"]}}},"receiptId":{"type":"string","title":"Receipt","pattern":"^rcp_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$","description":"The receipt of a charged read; POST /v1/credits/refunds can refund it. Absent when nothing was charged.","examples":["rcp_5c2e8a91-4b7d-4f36-9e10-8a2b3c4d5e6f"]}}},"Observation":{"type":"object","title":"Observation","description":"One reading of one product on one retailer, for one pin code, at one time: price, MRP and availability as the retailer showed them. Never a ranking, and never a stock claim for Flipkart.","additionalProperties":false,"required":["id","retailer","retailerSku","pincode","observedAt","ingestedAt","currency","source","evidence"],"properties":{"id":{"type":"integer","title":"Observation id","description":"Stable identifier of this reading; cite it when disputing a value.","examples":[48210377]},"retailer":{"type":"string","title":"Retailer","description":"The retailer key, as listed by /v1/data/retailers.","examples":["blinkit"]},"retailerSku":{"type":"string","title":"Retailer product id","description":"The retailer's own product identifier. Unique within one retailer only.","examples":["prd-88213"]},"pincode":{"type":"string","title":"Pin code","description":"The Indian pin code the page was read for, or national when the page is not pin-scoped.","examples":["110092"]},"observedAt":{"type":"string","format":"date-time","title":"Observed at","description":"When the retailer's page was read.","examples":["2026-10-14T09:27:00Z"]},"ingestedAt":{"type":"string","format":"date-time","title":"Ingested at","description":"When the reading entered Rewalto's store.","examples":["2026-10-14T10:40:00Z"]},"title":{"type":["null","string"],"title":"Title","description":"The product title as the retailer showed it.","examples":["Aashirvaad Atta 5 kg"]},"brand":{"type":["null","string"],"title":"Brand","description":"The brand as the retailer attributed it; often absent or wrong.","examples":["Aashirvaad"]},"packSizeRaw":{"type":["null","string"],"title":"Pack size","description":"The pack size exactly as printed, unparsed.","examples":["5 kg"]},"priceMinor":{"type":["null","integer"],"title":"Selling price (paise)","description":"Selling price in paise; null when it could not be read, never 0 for unknown.","examples":[28500]},"mrpMinor":{"type":["null","integer"],"title":"MRP (paise)","description":"Maximum retail price in paise; null when the retailer published none.","examples":[31000]},"currency":{"type":"string","enum":["INR"],"title":"Currency","description":"ISO 4217 code of the amounts.","examples":["INR"]},"inStock":{"type":["null","boolean"],"title":"In stock","description":"Availability as the page showed it; null when the page carried no signal. Always null for Flipkart.","examples":[true]},"category":{"type":["null","string"],"title":"Category","description":"The retailer's own category, not normalised across retailers.","examples":["atta-rice-dal"]},"productId":{"type":["null","string"],"format":"uuid","title":"Product id","description":"The matched Rewalto product, when the listing is matched to one.","examples":["0d6b4a52-4b6e-4c1a-9a7e-5b0d2f8f1a11"]},"sourceUrl":{"type":["null","string"],"title":"Source URL","description":"The page this reading was taken from.","examples":["https://blinkit.com/prn/aashirvaad-atta/prid/88213"]},"recipeVersion":{"type":["null","integer"],"title":"Recipe version","description":"Version of the extraction recipe that produced the reading.","examples":[5]},"source":{"type":"string","enum":["harvest"],"title":"Source","description":"Always harvest: Rewalto's own collection.","examples":["harvest"]},"evidence":{"$ref":"#/components/schemas/Evidence"}}},"RatingChange":{"type":"object","title":"RatingChange","description":"A listing’s rating, rating count and review count on an IST day when one of them changed, at one pin code (or national), from that day’s newest reading.","additionalProperties":false,"required":["retailer","retailerSku","pincode","day","rating","ratingCount","reviewCount","observationId","observedAt"],"properties":{"retailer":{"type":"string","title":"Retailer","description":"The retailer.","examples":["nykaa"]},"retailerSku":{"type":"string","title":"Retailer SKU","description":"The retailer's own product id.","examples":["1234567"]},"pincode":{"type":"string","title":"Pin code","description":"The pin code, or national.","examples":["national"]},"day":{"type":"string","format":"date","title":"Day","description":"The IST day of the change.","examples":["2026-10-16"]},"rating":{"type":["null","number"],"title":"Rating","description":"The rating out of 5, to two decimals; null when the page showed none.","examples":[4.21]},"ratingCount":{"type":["null","integer"],"title":"Rating count","description":"How many ratings.","examples":[1834]},"reviewCount":{"type":["null","integer"],"title":"Review count","description":"How many written reviews.","examples":[402]},"observationId":{"type":"string","title":"Observation","description":"The kept reading the values come from (its source, fetch time, SHA-256 and the exact text read).","examples":["48210377"]},"observedAt":{"type":"string","format":"date-time","title":"Observed at","description":"When it was read.","examples":["2026-10-16T09:12:00Z"]}}},"DatasetSample":{"type":"object","title":"Dataset sample","description":"Real rows Rewalto keeps for one dataset, shaped exactly as its paid read delivers them, every one at least 7 days old. Never made up: an empty list means nothing old enough is kept yet.","additionalProperties":false,"required":["dataset","operationId","path","unit","catalogueEntryId","rows","notAfter","rate","generatedAt","available"],"properties":{"dataset":{"type":"string","enum":["listings","price_history","mentions","ratings","banners","storefront_promos","promo_emails","ad_creatives","dark_stores","brand_directory","storefronts","search_rank","sponsored_share","delivery_eta"],"title":"Dataset","description":"The dataset.","examples":["listings"]},"operationId":{"type":"string","title":"Operation","description":"The paid read that delivers this dataset.","examples":["listListings"]},"path":{"type":"string","title":"Path","description":"Its path.","examples":["/v1/data/listings"]},"unit":{"type":"string","title":"Unit","description":"The rate-card unit it is charged in.","examples":["listings"]},"catalogueEntryId":{"type":["null","string"],"title":"Catalogue entry","description":"Its own catalogue entry, where it has one.","examples":["lib_promo_emails"]},"rows":{"type":"array","title":"Rows","description":"Up to 12 real rows, each one record of the paid read; price history adds up to 5 per quick-commerce app, one per pin code.","items":{"type":"object","title":"Row","description":"One record, as the paid read delivers it.","additionalProperties":true}},"notAfter":{"type":"string","format":"date","title":"Not after","description":"No row is newer than the end of this IST day (7 days before today).","examples":["2026-10-13"]},"rate":{"type":["null","object"],"title":"Published rate","description":"A published rate from the newest rate card holding the unit (C-012): credits for every perUnits records. Null when no rate is published for the unit yet; that read is then refused with not_for_sale.","additionalProperties":false,"required":["unit","credits","perUnits","cardVersion"],"properties":{"unit":{"type":"string","title":"Unit","description":"The rate-card unit.","examples":["listings"]},"credits":{"type":"integer","title":"Credits","description":"Credits for every perUnits records.","examples":[1],"minimum":0},"perUnits":{"type":"integer","title":"Per units","description":"Records the credits cover.","examples":[10],"minimum":1},"cardVersion":{"type":"integer","title":"Rate card","description":"The rate card version the rate is on.","examples":[2],"minimum":1}}},"generatedAt":{"type":["null","string"],"format":"date-time","title":"Generated at","description":"When these rows were read from the Library (UTC). Samples are read off the request path and kept until the next IST day (issue #743); null when they could not be read.","examples":["2026-11-01T14:00:00.000Z"]},"available":{"type":"boolean","title":"Available","description":"False when the rows could not be read just now: rows is then empty and says nothing about what Rewalto holds; ask again later. True rows that are empty mean nothing that old is kept.","examples":[true]}}},"SearchRank":{"type":"object","title":"SearchRank","description":"Where one listing ranked for one search term at one pin code (or national) on one IST day, from every search reply Rewalto read that day. bestPlace is its best position in the whole result list, ads included; it is known only where the reply states where its page starts (a first page, or Blinkit’s offset), else null, and bestPage and bestPageSlot still say where it was seen.","additionalProperties":false,"required":["day","retailer","searchTerm","pincode","retailerSku","brand","bestPlace","bestPage","bestPageSlot","readings","top10Readings","adAwareReadings","sponsoredReadings","firstSeen","lastSeen"],"properties":{"day":{"type":"string","format":"date","title":"Day","description":"The IST day.","examples":["2026-10-21"]},"retailer":{"type":"string","title":"Retailer","description":"The retailer.","examples":["flipkart"]},"searchTerm":{"type":"string","title":"Search term","description":"The search term.","examples":["instant coffee"]},"pincode":{"type":"string","title":"Pin code","description":"The pin code searched at, or national.","examples":["national"]},"retailerSku":{"type":"string","title":"Retailer product id","description":"The retailer’s own product id.","examples":["COFG5Z7H2ZQ8YH5K"]},"brand":{"type":"string","title":"Brand","description":"The brand on the card; empty when it named none.","examples":["Nescafe"]},"bestPlace":{"type":["null","integer"],"minimum":1,"title":"Best place","description":"Best position in the whole result list that day (1 is first).","examples":[3]},"bestPage":{"type":"integer","minimum":0,"title":"Best page","description":"The first result page it was seen on (1 is the first page).","examples":[1]},"bestPageSlot":{"type":"integer","minimum":0,"title":"Slot on that page","description":"Its best position on that page, ads included.","examples":[3]},"readings":{"type":"integer","minimum":0,"title":"Readings","description":"Search replies that showed it that day.","examples":[4]},"top10Readings":{"type":"integer","minimum":0,"title":"Top-10 readings","description":"Of those, replies that placed it in places 1 to 10.","examples":[4]},"adAwareReadings":{"type":"integer","minimum":0,"title":"Ad-aware readings","description":"Replies from a reading that can see the ad marker.","examples":[4]},"sponsoredReadings":{"type":"integer","minimum":0,"title":"Sponsored readings","description":"Of the ad-aware replies, those that marked it sponsored.","examples":[0]},"firstSeen":{"type":"string","format":"date-time","title":"First seen","description":"The first reading that day.","examples":["2026-10-21T02:31:10.000000Z"]},"lastSeen":{"type":"string","format":"date-time","title":"Last seen","description":"The last reading that day.","examples":["2026-10-21T14:02:44.000000Z"]}}},"SponsoredShareCell":{"type":"object","title":"SponsoredShareCell","description":"The search slots one brand held for one search term at one pin code on one IST day, how many were marked sponsored, and its share of all the sponsored slots of that term, pin and day. A slot is one product card in one search reply Rewalto read; ad counts are only kept from replies whose reading can see the retailer’s ad marker (adAwareSlots), so a reply that cannot see ads never reads as \"no ads\".","additionalProperties":false,"required":["day","retailer","searchTerm","pincode","brand","slots","adAwareSlots","sponsoredSlots","organicSlots","top10AdAwareSlots","top10SponsoredSlots","termAdAwareSlots","termSponsoredSlots","sponsoredRate","shareOfSponsored","pages","firstSeen","lastSeen"],"properties":{"day":{"type":"string","format":"date","title":"Day","description":"The IST day.","examples":["2026-10-21"]},"retailer":{"type":"string","title":"Retailer","description":"The retailer.","examples":["blinkit"]},"searchTerm":{"type":"string","title":"Search term","description":"The search term.","examples":["shampoo"]},"pincode":{"type":"string","title":"Pin code","description":"The six-digit pin code searched at.","examples":["560034"]},"brand":{"type":"string","title":"Brand","description":"The brand on the card, as the retailer wrote it; empty when the card named none.","examples":["Dove"]},"slots":{"type":"integer","minimum":0,"title":"Slots","description":"Product cards of this brand in the replies read.","examples":[24]},"adAwareSlots":{"type":"integer","minimum":0,"title":"Ad-aware slots","description":"Of those, cards from a reading that can see the ad marker.","examples":[24]},"sponsoredSlots":{"type":"integer","minimum":0,"title":"Sponsored slots","description":"Of the ad-aware cards, those marked sponsored.","examples":[6]},"organicSlots":{"type":"integer","minimum":0,"title":"Organic slots","description":"Of the ad-aware cards, those the retailer itself states are organic (Tata 1mg only); 0 elsewhere.","examples":[0]},"top10AdAwareSlots":{"type":"integer","minimum":0,"title":"Top-10 ad-aware slots","description":"Ad-aware cards in places 1 to 10 of a reply page.","examples":[8]},"top10SponsoredSlots":{"type":"integer","minimum":0,"title":"Top-10 sponsored slots","description":"Sponsored cards in places 1 to 10 of a reply page.","examples":[3]},"termAdAwareSlots":{"type":"integer","minimum":0,"title":"Term ad-aware slots","description":"Ad-aware cards of every brand for this term, pin and day.","examples":[410]},"termSponsoredSlots":{"type":"integer","minimum":0,"title":"Term sponsored slots","description":"Sponsored cards of every brand for this term, pin and day.","examples":[52]},"sponsoredRate":{"type":["null","number"],"minimum":0,"maximum":1,"title":"Sponsored rate","description":"sponsoredSlots / adAwareSlots: how much of this brand’s shelf was bought; null when no card was ad-aware.","examples":[0.25]},"shareOfSponsored":{"type":["null","number"],"minimum":0,"maximum":1,"title":"Share of sponsored","description":"sponsoredSlots / termSponsoredSlots: this brand’s share of the bought slots of the term, pin and day; null when the term had no sponsored card.","examples":[0.1154]},"pages":{"type":"integer","minimum":0,"title":"Pages","description":"Reply pages that carried this brand.","examples":[4]},"firstSeen":{"type":"string","format":"date-time","title":"First seen","description":"The first reading that day.","examples":["2026-10-21T02:31:10.000000Z"]},"lastSeen":{"type":"string","format":"date-time","title":"Last seen","description":"The last reading that day.","examples":["2026-10-21T14:02:44.000000Z"]}}},"ListingImage":{"type":"object","title":"Image","description":"One image address as the source showed it, never the image itself (C-010). Position 0 is the primary image.","additionalProperties":false,"required":["url","position","source","firstSeen","lastSeen"],"properties":{"url":{"type":"string","title":"Image URL","description":"The image address.","examples":["https://images.example/lipstick-1.jpg"],"format":"uri"},"position":{"type":"integer","title":"Position","description":"0 is the primary image; then the order the source shows them in.","examples":[0],"minimum":0},"source":{"type":"string","title":"Source","description":"Where the address was read: a retailer key or a site domain.","examples":["nykaa"]},"firstSeen":{"type":"string","format":"date-time","title":"First seen","description":"When the address was first seen at this position.","examples":["2026-08-27T08:00:00Z"]},"lastSeen":{"type":"string","format":"date-time","title":"Last seen","description":"When the address was last seen at this position.","examples":["2026-10-14T09:00:00Z"]},"sha256":{"type":"string","title":"Image SHA-256","description":"SHA-256 of the image bytes, 64 lowercase hex; present only when Rewalto has read them.","examples":["9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"],"pattern":"^[0-9a-f]{64}$"}}},"Evidence":{"type":"object","title":"Evidence","description":"Proof of where the record came from: the SHA-256 of the fetched response. The response itself is not kept; the hash, the source URL and the time are.","additionalProperties":false,"required":["sha256","missing"],"properties":{"sha256":{"type":["null","string"],"title":"Response SHA-256","description":"64 lowercase hex characters; null when no hash was kept.","examples":["9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"]},"missing":{"type":"boolean","title":"Hash missing","description":"True when the response was not kept; the record still names its source URL and time.","examples":[false]}}}},"securitySchemes":{"sessionJwt":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A Clerk session token for a signed-in user: `Authorization: Bearer <token>`. Mint it in the frontend with the Clerk JWT template named `rewalto-core`, whose audience is `rewalto-core-api`. It carries `sub`, `org_id` and `org_role`. An expired token is `session_expired`."},"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"rwk_ API key","description":"An organisation API key: `Authorization: Bearer rwk_...`. Minted with `createKey`; the secret is shown once. A key carries scopes and an expiry of 7, 30 or 90 days.","x-scopes":["data:read","tools:run","usage:read"]},"serviceKey":{"type":"http","scheme":"bearer","bearerFormat":"rws_ service key","description":"A Rewalto service key, for Rewalto's own servers only: `Authorization: Bearer rws_...`. Minted and revoked by staff, never through the API; the secret is shown once. It carries scopes and an expiry, opens only `/v1/service` routes, and every call is audited.","x-scopes":["notification-preferences:read","intake:write","site-pages:read","evidence:read","ad-references:read","ad-references:report","external-data:connect","external-data:read","external-data:sync","external-data:delete"]}}},"x-error-codes":{"invalid_request":{"status":400,"retry":"fix_request"},"invalid_json":{"status":400,"retry":"fix_request"},"unauthenticated":{"status":401,"retry":"refresh_credentials"},"session_expired":{"status":401,"retry":"refresh_credentials"},"key_expired":{"status":401,"retry":"refresh_credentials"},"key_revoked":{"status":401,"retry":"refresh_credentials"},"credits_exhausted":{"status":402,"retry":"never"},"over_quote":{"status":402,"retry":"never"},"plan_required":{"status":402,"retry":"never"},"preview_needs_approval":{"status":402,"retry":"never"},"price_changed":{"status":409,"retry":"never"},"forbidden":{"status":403,"retry":"never"},"org_missing":{"status":403,"retry":"never"},"scope_missing":{"status":403,"retry":"never"},"not_entitled":{"status":403,"retry":"never"},"private_data":{"status":403,"retry":"never"},"access_control":{"status":403,"retry":"never"},"not_found":{"status":404,"retry":"fix_request"},"quote_expired":{"status":410,"retry":"fix_request"},"quote_already_approved":{"status":409,"retry":"never"},"refund_refused":{"status":409,"retry":"never"},"catalogue_refused":{"status":409,"retry":"never"},"not_for_sale":{"status":409,"retry":"never"},"export_not_ready":{"status":409,"retry":"never"},"download_expired":{"status":410,"retry":"fix_request"},"reopen_expired":{"status":410,"retry":"fix_request"},"idempotency_conflict":{"status":409,"retry":"never"},"stale_version":{"status":409,"retry":"never"},"package_not_ready":{"status":409,"retry":"never"},"upload_not_ready":{"status":409,"retry":"never"},"cost_changed":{"status":409,"retry":"never"},"billing_profile_missing":{"status":409,"retry":"never"},"export_not_available":{"status":409,"retry":"never"},"unknown_capability":{"status":404,"retry":"fix_request"},"schema_retired":{"status":410,"retry":"fix_request"},"payload_too_large":{"status":413,"retry":"fix_request"},"unsupported_media_type":{"status":415,"retry":"fix_request"},"rate_limited":{"status":429,"retry":"after_reset"},"internal":{"status":500,"retry":"bounded"},"evidence_unavailable":{"status":503,"retry":"bounded"},"payment_provider_unavailable":{"status":503,"retry":"bounded"},"checkout_unavailable":{"status":503,"retry":"bounded"},"invoicing_unavailable":{"status":409,"retry":"never"},"provider_access_pending":{"status":409,"retry":"never"},"connection_revoked":{"status":409,"retry":"never"},"owner_required":{"status":403,"retry":"never"},"provider_quota_exhausted":{"status":429,"retry":"after_reset"},"workspace_closed":{"status":409,"retry":"never"},"unavailable":{"status":503,"retry":"bounded"}}}