{"openapi":"3.1.0","info":{"title":"timesys.pro API","description":"Temporal infrastructure: multi-jurisdiction observance, announcement, tax, and exchange data.\n\n**Every datapoint carries an assurance level** — `verified` (human-checked against a primary source), `corroborated` (independent sources agree), or `compiled` (assembled from research) — plus date `precision`: `exact` (deterministic rule), `estimate` (calendar conversion, ±1 day), or `announced` (government-confirmed date).","version":"v1.24.0"},"paths":{"/version.json":{"get":{"tags":["meta"],"summary":"Version Json","operationId":"version_json_version_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/health":{"get":{"tags":["meta"],"summary":"Health","operationId":"health_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/jurisdictions":{"get":{"tags":["jurisdictions"],"summary":"List Jurisdictions","operationId":"list_jurisdictions_v1_jurisdictions_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"country|state|region|province|territory|municipality","title":"Type"},"description":"country|state|region|province|territory|municipality"},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"substring match on name","title":"Q"},"description":"substring match on name"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/jurisdictions/{code}":{"get":{"tags":["jurisdictions"],"summary":"Get Jurisdiction","operationId":"get_jurisdiction_v1_jurisdictions__code__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","title":"Code"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/observances/{code}":{"get":{"tags":["observances"],"summary":"Get Observances","operationId":"get_observances_v1_observances__code__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","title":"Code"}},{"name":"include_inherited","in":"query","required":false,"schema":{"type":"boolean","description":"Include records inherited from parent jurisdictions (state/city files hold only additions)","default":true,"title":"Include Inherited"},"description":"Include records inherited from parent jurisdictions (state/city files hold only additions)"},{"name":"assurance","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"compiled|corroborated|verified","title":"Assurance"},"description":"compiled|corroborated|verified"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/calendar":{"get":{"tags":["calendar"],"summary":"Calendar","operationId":"calendar_v1_calendar_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"jurisdictions","in":"query","required":true,"schema":{"type":"string","description":"comma-separated codes, e.g. SE,DE-BY","title":"Jurisdictions"},"description":"comma-separated codes, e.g. SE,DE-BY"},{"name":"from","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","title":"From"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","title":"To"}},{"name":"min_assurance","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"corroborated → exclude compiled; verified → verified only","title":"Min Assurance"},"description":"corroborated → exclude compiled; verified → verified only"},{"name":"tz","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"IANA zone of the CALLER, e.g. Asia/Tokyo. Adds UTC bounds for each holiday plus the date it falls on for you. Dates themselves are never shifted — a holiday is a civil date in its own jurisdiction.","title":"Tz"},"description":"IANA zone of the CALLER, e.g. Asia/Tokyo. Adds UTC bounds for each holiday plus the date it falls on for you. Dates themselves are never shifted — a holiday is a civil date in its own jurisdiction."},{"name":"categories","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"comma-separated categories, e.g. religious_islamic,religious_jewish. Omit for all.","title":"Categories"},"description":"comma-separated categories, e.g. religious_islamic,religious_jewish. Omit for all."},{"name":"closures_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only days that actually shut something. Excludes `optional` and `open` — the observe-but-working days.","default":false,"title":"Closures Only"},"description":"Only days that actually shut something. Excludes `optional` and `open` — the observe-but-working days."},{"name":"format","in":"query","required":false,"schema":{"type":"string","pattern":"^(json|csv|ics)$","description":"json (default), csv (one row per event, flattened), or ics (subscribable iCalendar feed of all-day events).","default":"json","title":"Format"},"description":"json (default), csv (one row per event, flattened), or ics (subscribable iCalendar feed of all-day events)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/tax/{code}":{"get":{"tags":["tax"],"summary":"Get Tax","description":"Statutory filing and payment deadlines.\n\nThe API has advertised tax data since v1.0 and had no route to reach it:\n640 deadlines in the artifact, unreachable. Inheritance applies as it does\nelsewhere — a subdivision sees its country's deadlines.\n\nA `manual_decree` rule returns no computed date on purpose. Most of these\nare conditional on a fiscal year end (\"within 6 months of FY-end\") and the\nhonest answer is the wording, not a fabricated date.","operationId":"get_tax_v1_tax__code__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","title":"Code"}},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"corporations|individuals|employers — filters applies_to","title":"Audience"},"description":"corporations|individuals|employers — filters applies_to"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/announcements/{code}":{"get":{"tags":["announcements"],"summary":"Get Announcements","operationId":"get_announcements_v1_announcements__code__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","title":"Code"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/exchanges":{"get":{"tags":["exchanges"],"summary":"List Exchanges","operationId":"list_exchanges_v1_exchanges_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/exchanges/{mic}":{"get":{"tags":["exchanges"],"summary":"Get Exchange","operationId":"get_exchange_v1_exchanges__mic__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"mic","in":"path","required":true,"schema":{"type":"string","title":"Mic"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/exchanges/{mic}/calendar":{"get":{"tags":["exchanges"],"summary":"Exchange Calendar","description":"Resolved trading-calendar closures: jurisdiction holidays\n(substitution applied, exclusions removed) plus exchange-specific\nclosures, session days only.","operationId":"exchange_calendar_v1_exchanges__mic__calendar_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"mic","in":"path","required":true,"schema":{"type":"string","title":"Mic"}},{"name":"from","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","title":"From"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","title":"To"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","pattern":"^(json|csv|ics)$","description":"json (default), csv, or ics (subscribable feed).","default":"json","title":"Format"},"description":"json (default), csv, or ics (subscribable feed)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/catalog":{"get":{"tags":["meta"],"summary":"Catalog","description":"The menu: every option the API offers — calendars, holidays, tax, market\ncalendars, sun & season — each with a context blurb (who observes it, where\nit's official) and a `new` flag.\n\nServes the baked catalog.json (generated at ship-time by ship.sh, with full\ndataset context) if present — that's the production path. Falls back to\nbuilding live from the registry in dev. Cached in-process, invalidated by\nmtime.","operationId":"catalog_v1_catalog_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/plans":{"get":{"tags":["meta"],"summary":"Plans Public","description":"Every plan and what it grants. Unauthenticated, because the console is.\n\nTHE CONSOLE USED TO CARRY ITS OWN COPY of this table, and the copy went\nstale the day the plans were renamed: a public page went on offering\n\"Professional\" and \"Business\" tiers that nothing sells, and locking\nfeatures behind them. A pricing surface and the enforcer that honours it\nmust not be two files.\n\nNothing here is a secret — it is what the pricing page says out loud. The\n`notes` and `approval_required` fields come along because the console\nexplains locks with them.","operationId":"plans_public_v1_plans_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/solar":{"get":{"tags":["solar"],"summary":"Solar","description":"Daylight duration + approximate sun times for a location/date. Computed\nLIVE (deterministic, any year) — no DB, no precompute. Duration is exact to\n~minutes and self-clamps to 24h/0h at the poles; install `astral` on the\nhost for precise clock times / twilight.","operationId":"solar_v1_solar_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","maximum":90,"minimum":-90,"title":"Lat"}},{"name":"lon","in":"query","required":false,"schema":{"type":"number","maximum":180,"minimum":-180,"default":0.0,"title":"Lon"}},{"name":"date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","title":"Date"}},{"name":"tz_offset","in":"query","required":false,"schema":{"type":"number","maximum":14,"minimum":-14,"default":0.0,"title":"Tz Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/calendars/overlay":{"get":{"tags":["calendar"],"summary":"Calendar Overlay","description":"A Gregorian date rendered across every parallel calendar system —\nCoptic / Ethiopic / Julian / Hebrew / Discordian plus the Class-A\nreckonings (Persian, Maya, Egyptian, Armenian, counters, year-offsets).\nComputed live; deterministic for any year.","operationId":"calendar_overlay_v1_calendars_overlay_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","title":"Date"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account":{"get":{"tags":["meta"],"summary":"Account","description":"What this key is and what it may reach.\n\nUsage is reported because a customer is entitled to see it, NOT because it\nis billed — there is no volume component to any plan. Saying that in the\npayload rather than only in the pricing page keeps the two honest.","operationId":"account_v1_account_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/coverage":{"get":{"tags":["meta"],"summary":"Coverage","description":"Assurance coverage per country — the honesty dashboard.","operationId":"coverage_v1_coverage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/billing/checkout":{"post":{"tags":["billing"],"summary":"Billing Checkout","description":"Start a purchase. Returns the Stripe-hosted URL to send the buyer to.\n\nNo auth: buying is how you GET a key, so requiring one would be a loop.\nThe endpoint is safe to leave open because it creates nothing of ours —\na Checkout Session that is never paid leaves no trace here at all.","operationId":"billing_checkout_v1_billing_checkout_post","parameters":[{"name":"plan","in":"query","required":true,"schema":{"type":"string","title":"Plan"}},{"name":"email","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"}},{"name":"units","in":"query","required":false,"schema":{"type":"integer","maximum":240,"minimum":1,"default":1,"title":"Units"}},{"name":"territory","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":8},{"type":"null"}],"description":"ISO 3166 code the dossier is for. Required for a dossier plan.","title":"Territory"},"description":"ISO 3166 code the dossier is for. Required for a dossier plan."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account/rotate":{"post":{"tags":["meta"],"summary":"Account Rotate","description":"Replace this key with a new one. The old one stops working immediately.\n\nTHE ONLY ANSWER WE CAN HONESTLY GIVE to \"I lost my key\" or \"my key leaked\",\nbecause we hold a hash and cannot reproduce the original. Plan, Stripe\nlinkage and claimed jurisdictions all carry over — see keystore.rotate for\nwhy each of those matters.\n\nAuthenticated by the key being replaced, which means it covers a leak and\nnot a loss. Recovering from a total loss needs proof of identity we do not\nyet collect; until then that is a support email and a hand-issued key.","operationId":"account_rotate_v1_account_rotate_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/billing/portal":{"post":{"tags":["billing"],"summary":"Billing Portal","description":"Invoices, card, cancellation — on Stripe's pages, not ours.","operationId":"billing_portal_v1_billing_portal_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}}}