{"openapi":"3.1.0","info":{"title":"EggRate India API","version":"v1","summary":"Daily NECC egg rates for Indian markets.","description":"Every price is returned as integer paise per egg (the authoritative value), alongside rupee and per-unit representations. Responses are wrapped in a `{ success, meta, data }` envelope.","contact":{"name":"EggRate India","url":"https://eggrate-web.eggrates19.workers.dev/contact"},"license":{"name":"Data: NECC declared rates","identifier":"CC-BY-4.0"}},"servers":[{"url":"https://eggrate-api.eggrates19.workers.dev/api/v1","description":"Production"},{"url":"http://127.0.0.1:8787/api/v1","description":"Local wrangler dev"}],"tags":[{"name":"Rates","description":"Daily prices and history."},{"name":"Catalog","description":"Markets and states."},{"name":"Meta","description":"Index, health and this document."},{"name":"Forms","description":"Newsletter and contact submissions."},{"name":"Admin","description":"Rate ingestion. Requires a bearer token."}],"paths":{"/":{"get":{"tags":["Meta"],"summary":"API index","responses":{"200":{"description":"Endpoint directory.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/health":{"get":{"tags":["Meta"],"summary":"Health check with D1 coverage stats","responses":{"200":{"description":"Service is healthy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"503":{"description":"Error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/rates/today":{"get":{"tags":["Rates"],"summary":"Rate board for a single day","parameters":[{"name":"date","in":"query","required":false,"description":"Calendar date in YYYY-MM-DD. Defaults to today in IST.","schema":{"type":"string","format":"date"}},{"name":"state","in":"query","required":false,"description":"Filter to one state slug, for example `haryana`.","schema":{"type":"string"}},{"name":"zone","in":"query","required":false,"schema":{"type":"string","enum":["North","South","East","West","Central"]}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["market","rate_asc","rate_desc","change_desc","state"],"default":"market"}},{"name":"unit","in":"query","required":false,"description":"Which unit the caller intends to highlight.","schema":{"type":"string","enum":["piece","tray","hundred","peti"],"default":"piece"}}],"responses":{"200":{"description":"One row per market.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateListEnvelope"}}}},"400":{"description":"Error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/rates/{market}":{"get":{"tags":["Rates"],"summary":"Current rate for one market","parameters":[{"name":"market","in":"path","required":true,"description":"Market slug, for example `barwala` or `west-godavari`.","schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}},{"name":"date","in":"query","required":false,"description":"Calendar date in YYYY-MM-DD. Defaults to today in IST.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"The market rate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateEnvelope"}}}},"404":{"description":"Error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/rates/{market}/history":{"get":{"tags":["Rates"],"summary":"Daily price series","parameters":[{"name":"market","in":"path","required":true,"description":"Market slug, for example `barwala` or `west-godavari`.","schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}},{"name":"date","in":"query","required":false,"description":"Calendar date in YYYY-MM-DD. Defaults to today in IST.","schema":{"type":"string","format":"date"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":2,"maximum":730,"default":30}}],"responses":{"200":{"description":"Series plus descriptive stats.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/rates/{market}/monthly":{"get":{"tags":["Rates"],"summary":"Monthly averages","parameters":[{"name":"market","in":"path","required":true,"description":"Market slug, for example `barwala` or `west-godavari`.","schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}},{"name":"months","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":36,"default":12}}],"responses":{"200":{"description":"One row per calendar month.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/summary":{"get":{"tags":["Rates"],"summary":"National roll-up and zone averages","parameters":[{"name":"date","in":"query","required":false,"description":"Calendar date in YYYY-MM-DD. Defaults to today in IST.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Summary payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/trends":{"get":{"tags":["Rates"],"summary":"Biggest movers, cheapest and dearest markets","parameters":[{"name":"date","in":"query","required":false,"description":"Calendar date in YYYY-MM-DD. Defaults to today in IST.","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":34,"default":6}}],"responses":{"200":{"description":"Trend buckets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/markets":{"get":{"tags":["Catalog"],"summary":"Market master list","parameters":[{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"zone","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Markets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/markets/{market}":{"get":{"tags":["Catalog"],"summary":"Everything about one market in a single call","parameters":[{"name":"market","in":"path","required":true,"description":"Market slug, for example `barwala` or `west-godavari`.","schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}},{"name":"date","in":"query","required":false,"description":"Calendar date in YYYY-MM-DD. Defaults to today in IST.","schema":{"type":"string","format":"date"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":2,"maximum":365,"default":30}},{"name":"months","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":24,"default":6}}],"responses":{"200":{"description":"Market detail bundle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/states":{"get":{"tags":["Catalog"],"summary":"States with the day price band","parameters":[{"name":"date","in":"query","required":false,"description":"Calendar date in YYYY-MM-DD. Defaults to today in IST.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"States.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/states/{state}":{"get":{"tags":["Catalog"],"summary":"One state and its markets","parameters":[{"name":"state","in":"path","required":true,"schema":{"type":"string"}},{"name":"date","in":"query","required":false,"description":"Calendar date in YYYY-MM-DD. Defaults to today in IST.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"State detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/catalog":{"get":{"tags":["Catalog"],"summary":"States and markets together","responses":{"200":{"description":"Catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/subscribe":{"post":{"tags":["Forms"],"summary":"Join the daily rate email","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"market":{"type":"string","description":"Optional market slug to follow."}}}}}},"responses":{"200":{"description":"Subscribed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"422":{"description":"Error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/contact":{"post":{"tags":["Forms"],"summary":"Send a message","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email","message"],"properties":{"name":{"type":"string","minLength":2,"maxLength":120},"email":{"type":"string","format":"email"},"company":{"type":"string","maxLength":160},"message":{"type":"string","minLength":10,"maxLength":4000}}}}}},"responses":{"200":{"description":"Message stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"422":{"description":"Error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/admin/rates":{"post":{"tags":["Admin"],"summary":"Ingest declared rates for a date","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["date","rates"],"properties":{"date":{"type":"string","format":"date"},"source":{"type":"string","default":"manual"},"rates":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"object","required":["market"],"properties":{"market":{"type":"string"},"paise":{"type":"integer","minimum":100,"maximum":3000},"rupees":{"type":"number","minimum":1,"maximum":30}}}}}}}}},"responses":{"200":{"description":"Rows written.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/admin/carry-forward":{"post":{"tags":["Admin"],"summary":"Repeat the last known rate for markets missing a date","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Rows written.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/admin/stats":{"get":{"tags":["Admin"],"summary":"Row counts and coverage window","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Stats.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The ADMIN_TOKEN secret."}},"schemas":{"Envelope":{"type":"object","required":["success","meta","data"],"properties":{"success":{"type":"boolean","const":true},"meta":{"type":"object","additionalProperties":true},"data":{}}},"ErrorEnvelope":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["bad_request","not_found","unauthorized","rate_limited","conflict","unprocessable","internal_error","no_data"]},"message":{"type":"string"},"details":{}}}}},"Price":{"type":"object","required":["eggs","paise","rupees","display"],"properties":{"eggs":{"type":"integer","examples":[30]},"paise":{"type":"integer","examples":[16830]},"rupees":{"type":"number","examples":[168.3]},"display":{"type":"string","examples":["₹168"]}}},"Change":{"type":"object","required":["paise","rupees","percent","direction","display"],"properties":{"paise":{"type":"integer","examples":[3]},"rupees":{"type":"number","examples":[0.03]},"percent":{"type":"number","examples":[0.54]},"direction":{"type":"string","enum":["up","down","flat"]},"display":{"type":"string","examples":["+₹0.03"]},"since":{"type":["string","null"],"format":"date"}}},"MarketRate":{"type":"object","required":["market","name","state","zone","paise"],"properties":{"market":{"type":"string","examples":["barwala"]},"name":{"type":"string","examples":["Barwala"]},"state":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"}}},"zone":{"type":"string"},"rate_date":{"type":["string","null"],"format":"date"},"paise":{"type":["integer","null"],"examples":[561]},"rupees":{"type":["number","null"],"examples":[5.61]},"prices":{"type":["object","null"],"properties":{"piece":{"$ref":"#/components/schemas/Price"},"tray":{"$ref":"#/components/schemas/Price"},"hundred":{"$ref":"#/components/schemas/Price"},"peti":{"$ref":"#/components/schemas/Price"}}},"change":{"oneOf":[{"$ref":"#/components/schemas/Change"},{"type":"null"}]}}},"RateEnvelope":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MarketRate"}}}]},"RateListEnvelope":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketRate"}}}}]}}}}