{"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":"flipkart_minutes"},"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/dark-stores":{"get":{"operationId":"listDarkStores","summary":"List quick-commerce dark stores and their catchments","description":"Each dark store Rewalto holds on Blinkit, Zepto, Instamart, BigBasket, Flipkart Minutes, JioMart and DMart, every source merged into one record per store: the app’s store id and name, the pin code, area, address, point, city and state where it is (each with where it came from), the pin codes it was seen serving, when it was first and last seen, whether it is open, newly opened or closed, and which sources hold it (the old weekly sweep, Core’s own weekly serviceability sweeps, which add stores as they run, Rewalto’s other readings of the app, and store lists Rewalto holds). Kept data, served as it stands (the newest last-seen day shows how current it is). Newest last-seen day first, optionally one platform, one city, one status, a day range, and pincode for the stores that serve that pin. BigBasket’s BB Now delivery areas are not stores and are not in it (they are counted apart in GET /v1/dark-stores/summary). Catalogue entry qc_dark_store_map; one record is one dark store. 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":{"type":"object","title":"Dark stores 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":{"type":"object","title":"DarkStore","description":"One quick-commerce dark store Rewalto holds, every source merged into one record (C-029): its app, store id, name, the pin code, area, address, point, city and state where it is, the pin codes it was seen serving (its catchment), when it was first and last seen, and whether it is open, newly opened or closed.","additionalProperties":false,"required":["day","source","platform","storeId","name","city","cityTier","status","sweepStatus","catchmentPins","catchmentPoints","firstSeen","lastSeen","closedAt","seenSweeps","missedSweeps","lat","lon","id","sources","homePincode","pincodeSource","area","address","state","country","coordSource"],"properties":{"day":{"type":"string","format":"date","title":"Day","description":"The IST day the store was last seen. The order and the from and to filters use this day.","examples":["2026-10-15"]},"source":{"type":"string","enum":["old_sweep","core_sweep","app_reading","store_list"],"title":"Source","description":"Where its status comes from: old_sweep (the weekly sweeps up to 17 Oct 2026) or core_sweep (Core’s weekly serviceability sweeps), the one that saw it most recently; for a store no sweep has seen, app_reading (Rewalto’s other readings of the app: its locator, product readings at a pin) or store_list (a store list Rewalto holds). Every source that holds the store is in sources.","examples":["old_sweep"]},"platform":{"type":"string","title":"Platform","description":"The quick-commerce app: blinkit, zepto, instamart, bigbasket, flipkart_minutes or jiomart.","examples":["blinkit"],"pattern":"^[a-z0-9_]{2,40}$"},"storeId":{"type":"string","title":"Store id","description":"The app’s own id for the store; for a store known only from a store list, Rewalto’s own id for it (ds-<id>).","examples":["1234"]},"name":{"type":["null","string"],"title":"Name","description":"The store name the app states; null when it states none.","examples":["HSR"]},"city":{"type":["null","string"],"title":"City","description":"The city the sweep found it in, else the city of its first catchment pin; null when neither is known.","examples":["Bengaluru"]},"cityTier":{"type":["null","string"],"enum":["tier_1_metro","tier_2","tier_3",null],"title":"City tier","description":"The city’s tier from the Government of India’s house rent allowance classes (DoE O.M. No. 2/5/2017-E.II(B), 7 Jul 2017): tier_1_metro (X), tier_2 (Y), tier_3 (every other city, Z); null where the city is not known.","examples":["tier_2"]},"status":{"type":"string","enum":["open","opened","closed"],"title":"Status","description":"open (seen in the sweeps since the first one), opened (first seen after the first sweep of its city: a new store) or closed (no longer seen).","examples":["open"]},"sweepStatus":{"type":"string","title":"Sweep status","description":"The sweep’s own status word. old_sweep: active, opened, flicker (missed in one sweep and seen again) or closed. core_sweep: seen (in the app’s newest sweep week) or missed.","examples":["active"]},"catchmentPins":{"type":"array","title":"Catchment pin codes","description":"The pin codes the store was seen serving, ascending.","items":{"type":"string","pattern":"^[1-9][0-9]{5}$"},"examples":[["560034","560102"]]},"catchmentPoints":{"type":"array","title":"Catchment points","description":"Sweep grid points (latitude,longitude) the store was seen serving that the sweep did not place on a pin code; empty for most stores.","items":{"type":"string"},"examples":[["22.48303,88.35303"]]},"firstSeen":{"type":"string","format":"date-time","title":"First seen","description":"When a sweep first saw the store (UTC).","examples":["2026-10-13T14:30:26.000Z"]},"lastSeen":{"type":"string","format":"date-time","title":"Last seen","description":"When a sweep last saw the store (UTC).","examples":["2026-10-15T16:27:27.000Z"]},"closedAt":{"type":["null","string"],"format":"date-time","title":"Closed at","description":"When the store was marked closed; null while open.","examples":["2026-10-20T00:00:00.000Z"]},"seenSweeps":{"type":["null","integer"],"title":"Sweeps seen","description":"How many sweeps saw the store; null for core_sweep stores.","examples":[2]},"missedSweeps":{"type":"integer","title":"Sweeps missed","description":"How many sweeps since it was last seen missed it.","examples":[0],"minimum":0},"lat":{"type":["null","number"],"title":"Latitude","description":"Latitude when located; null otherwise.","examples":[12.9116]},"lon":{"type":["null","number"],"title":"Longitude","description":"Longitude when located; null otherwise.","examples":[77.6389]},"id":{"type":"string","title":"Id","description":"Rewalto’s own id for the store, stable across refreshes.","examples":["1042"],"pattern":"^[0-9]+$"},"sources":{"type":"array","title":"Sources","description":"Every kind of source that holds the store (old_sweep, core_sweep, app_reading, store_list).","items":{"type":"string","enum":["old_sweep","core_sweep","app_reading","store_list"]},"examples":[["old_sweep","app_reading"]]},"homePincode":{"type":["null","string"],"pattern":"^[1-9][0-9]{5}$","title":"Pin code","description":"The pin code the store is in; null when unknown. pincodeSource says how it is known: an estimate (catchment, catchment_point) is the pin it serves most, not its address.","examples":["560034"]},"pincodeSource":{"type":["null","string"],"enum":["old_sweep","core_sweep","app_reading","store_list","pin_code","nearest_pin_centre","catchment","catchment_point","served_points_centroid","store_label",null],"title":"Pin code source","description":"app_reading or store_list (stated), nearest_pin_centre (the pin whose centre is nearest the store’s own point), catchment (its most-seen catchment pin) or catchment_point (the pin nearest a grid point it served); null with no pin.","examples":["catchment"]},"area":{"type":["null","string"],"title":"Area","description":"The locality the store is in: as a source stated it, else the main locality of its pin code (India Post); null when unknown.","examples":["Koramangala"]},"address":{"type":["null","string"],"title":"Address","description":"The store’s address as the app or a store list states it; null when none does.","examples":["Sector 110, Gurugram, Haryana, 122017"]},"state":{"type":["null","string"],"title":"State","description":"The state: as a source stated it, else its pin code’s; null when unknown.","examples":["Karnataka"]},"country":{"type":"string","title":"Country","description":"ISO 3166-1 alpha-2 country code.","examples":["IN"],"pattern":"^[A-Z]{2}$"},"coordSource":{"type":["null","string"],"enum":["old_sweep","core_sweep","app_reading","store_list","pin_code","nearest_pin_centre","catchment","catchment_point","served_points_centroid","store_label",null],"title":"Point source","description":"Where lat and lon come from: the app’s own statement of the store’s point (old_sweep, core_sweep, app_reading), or served_points_centroid, the centroid of the points the store served, derived by Rewalto because the app states none; null when not located.","examples":["core_sweep"]}}}},"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"}}}}}}}},"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":"platform","in":"query","required":false,"schema":{"type":"string","title":"Platform","examples":["blinkit"],"pattern":"^[a-z0-9_]{2,40}$"},"description":"The quick-commerce app: blinkit, zepto, instamart, bigbasket, flipkart_minutes or jiomart."},{"name":"city","in":"query","required":false,"schema":{"type":"string","title":"City","examples":["Bengaluru"],"minLength":2,"maxLength":100},"description":"Only stores in this city (any spelling core knows: Gurgaon finds Gurugram)."},{"name":"cities","in":"query","required":false,"schema":{"type":"string","title":"Cities","examples":["Bengaluru,Mysuru"],"minLength":2,"maxLength":2000},"description":"Only stores in any of these cities, comma-separated (up to 50; any spelling core knows). With city, both apply."},{"name":"state","in":"query","required":false,"schema":{"type":"string","title":"State","examples":["Karnataka"],"minLength":2,"maxLength":100},"description":"Only stores in this state or union territory (its home pin code’s state, else the one a source stated; any case, \"and\" or \"&\"). The states with stores are in GET /v1/dark-stores/filter-options."},{"name":"cityGroup","in":"query","required":false,"schema":{"type":"string","pattern":"^(tier_1_metro|tier_2|tier_3)$","title":"City group","examples":["tier_1_metro"]},"description":"Only stores in a curated city group: tier_1_metro, tier_2 or tier_3, the house rent allowance classes X, Y and Z (DoE O.M. No. 2/5/2017-E.II(B), 7 Jul 2017). Definitions in GET /v1/dark-stores/filter-options. Stores with no known city are in no group."},{"name":"pincode","in":"query","required":false,"schema":{"type":"string","title":"Pin code","examples":["560034"],"pattern":"^[1-9][0-9]{5}$"},"description":"Only stores that serve this six-digit pin code."},{"name":"status","in":"query","required":false,"schema":{"type":"string","title":"Status","examples":["opened"],"pattern":"^(open|opened|closed)$"},"description":"Only stores with this status: open, opened or closed."},{"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."},{"name":"selectionToken","in":"query","required":false,"schema":{"type":"string","title":"Selection token","examples":["dss1.eyJ2IjoxfQ"],"pattern":"^dss1\\.[A-Za-z0-9_-]{1,8000}$"},"description":"Optional: the selectionToken of a free GET /v1/data/dark-stores/preview for the same filters and limit. With it the page is delivered and charged only if its records and the rate are still the ones previewed; otherwise 409 cost_changed (preview again) or 410 quote_expired, and nothing is charged."}]}},"/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/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"}}}}}}}},"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"]}}},"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"}}}}},"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"]}}}}},"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}$"}}}},"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"}}}