{"openapi":"3.1.0","info":{"title":"Dealcalendar API","version":"0.1.0","description":"A fully local worldwide shopping-event calendar: fixed-formula events (Black Friday, Cyber Monday, Green Monday, Singles Day/11.11, the 618 festival, Boxing Day) computed live for any year, and retailer-announced/lunar-calendar events (Amazon Prime Day and its October sale, Diwali sales) from a hand-verified historical/typical-date table.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://dealcalendar.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/dealcalendar/docs"},"termsOfService":"https://connectorbay.com/dealcalendar/terms"},"servers":[{"url":"https://dealcalendar.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/dealcalendar/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/calendar_overview":{"post":{"operationId":"calendar_overview","summary":"Every shopping event this calendar covers, with region and whether its date is fixed-formula or","description":"Every shopping event this calendar covers, with region and whether its date is fixed-formula or\n    retailer-announced/variable. Use for \"what shopping events do you track\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"calendar_overviewArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/event_info":{"post":{"operationId":"event_info","summary":"One event's full detail: description, region, origin/history, and (for fixed-formula events) the","description":"One event's full detail: description, region, origin/history, and (for fixed-formula events) the\n    calendar rule used to compute its date. Use calendar_overview to see valid ids. Use for \"what is Green\n    Monday\", \"where did Singles Day come from\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"event_id":{"description":"An event's id or name.","examples":["black_friday","prime_day","diwali_sales","singles_day"],"title":"Event Id","type":"string"}},"required":["event_id"],"title":"event_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/dates_for_year":{"post":{"operationId":"dates_for_year","summary":"An event's date(s) for a specific year. Fixed-formula events (Black Friday, Cyber Monday, Green Monday,","description":"An event's date(s) for a specific year. Fixed-formula events (Black Friday, Cyber Monday, Green Monday,\n    Singles Day, 618, Boxing Day) are computed and work for any year. For Amazon Prime Day/Big Deal Days and\n    Diwali, returns the verified date if that year is in the table, or says plainly it isn't yet known. Use for\n    \"when is Black Friday in 2027\", \"what date was Prime Day in 2023\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"event_id":{"description":"An event's id or name.","title":"Event Id","type":"string"},"year":{"description":"The year to get the date(s) for.","maximum":2100,"minimum":1990,"title":"Year","type":"integer"}},"required":["event_id","year"],"title":"dates_for_yearArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/next_occurrence":{"post":{"operationId":"next_occurrence","summary":"The next time an event happens, from today (or a given date). Use for \"when's the next Black Friday\",","description":"The next time an event happens, from today (or a given date). Use for \"when's the next Black Friday\",\n    \"how long until the next Prime Day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"event_id":{"description":"An event's id or name.","title":"Event Id","type":"string"},"from_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Find the next occurrence after this date instead of today; YYYY-MM-DD.","title":"From Date"}},"required":["event_id"],"title":"next_occurrenceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/days_until":{"post":{"operationId":"days_until","summary":"A quick countdown: how many days until an event's next occurrence. Use for \"how many days until Black","description":"A quick countdown: how many days until an event's next occurrence. Use for \"how many days until Black\n    Friday\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"event_id":{"description":"An event's id or name.","title":"Event Id","type":"string"},"from_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Count from this date instead of today; YYYY-MM-DD.","title":"From Date"}},"required":["event_id"],"title":"days_untilArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/historical_dates":{"post":{"operationId":"historical_dates","summary":"The full verified year-by-year date table for a retailer-announced event (Amazon Prime Day, Prime Big","description":"The full verified year-by-year date table for a retailer-announced event (Amazon Prime Day, Prime Big\n    Deal Days) or the lunar-calendar Diwali sales season. Use for \"show me every past Prime Day date\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"event_id":{"description":"An event's id or name — must be a retailer-announced or lunar-calendar event (e.g. prime_day, diwali_sales), not a fixed-formula one.","title":"Event Id","type":"string"}},"required":["event_id"],"title":"historical_datesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/all_events_for_year":{"post":{"operationId":"all_events_for_year","summary":"Every covered event's date(s) for one year, listed chronologically (events with an unknown/unannounced","description":"Every covered event's date(s) for one year, listed chronologically (events with an unknown/unannounced\n    date for that year listed last). Use for \"give me the full shopping calendar for 2027\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"year":{"description":"The year to list every event's date(s) for.","maximum":2100,"minimum":1990,"title":"Year","type":"integer"}},"required":["year"],"title":"all_events_for_yearArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_events":{"post":{"operationId":"search_events","summary":"Keyword search across every event's name, region, description and origin. Use for \"what shopping events","description":"Keyword search across every event's name, region, description and origin. Use for \"what shopping events\n    happen in China\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Keyword to search for.","minLength":1,"title":"Query","type":"string"}},"required":["query"],"title":"search_eventsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/events_by_region":{"post":{"operationId":"events_by_region","summary":"Every event whose region tag matches a keyword. Use for \"what shopping events are there in India\".","description":"Every event whose region tag matches a keyword. Use for \"what shopping events are there in India\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"A region/country keyword.","examples":["US","China","India","UK","Canada"],"title":"Region","type":"string"}},"required":["region"],"title":"events_by_regionArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}