{"openapi":"3.1.0","info":{"title":"Kalender Sync API","version":"1.0.0","description":"Publish events as hosted calendar feeds and keep subscribers in sync."},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer"}},"schemas":{}},"paths":{"/v1/me":{"get":{"summary":"Check the API key","description":"Returns the account, mode and scopes of the key. Useful for a \"Test connection\" button.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"string"},"key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"mode":{"type":"string","enum":["live","test"]},"scopes":{"type":"array","items":{"type":"string"}},"calendar_ids":{"type":["array","null"],"items":{"type":"string"}}},"required":["id","name","mode","scopes","calendar_ids"],"additionalProperties":false}},"required":["account_id","key"],"additionalProperties":false}}}}}}},"/v1/publisher/calendars":{"post":{"summary":"Create a calendar","tags":["Publisher"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":["string","null"],"maxLength":1000},"timezone":{"type":"string"},"site_url":{"type":["string","null"],"maxLength":2000},"language":{"type":"string","enum":["en","de"]},"default_duration":{"type":"string"},"brand_color":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$"},"organizer":{"type":["object","null"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"url":{"type":["string","null"],"maxLength":2000},"email":{"type":["string","null"],"format":"email","maxLength":254}},"required":["name"],"additionalProperties":false},"show_events":{"type":"boolean"}},"required":["name","timezone"],"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"mode":{"type":"string","enum":["live","test"]},"name":{"type":"string"},"description":{"type":["string","null"]},"timezone":{"type":"string"},"site_url":{"type":["string","null"]},"language":{"type":"string","enum":["en","de"]},"default_duration":{"type":"string"},"brand_color":{"type":["string","null"]},"organizer":{"type":["object","null"],"properties":{"name":{"type":"string"},"url":{"type":["string","null"]},"email":{"type":["string","null"]}},"required":["name","url","email"],"additionalProperties":false},"show_events":{"type":"boolean"},"blocked":{"type":"boolean"},"logo_url":{"type":["string","null"]},"banner_url":{"type":["string","null"]},"subscribe_page_url":{"type":"string"},"feed_url":{"type":"string"},"subscribe_links":{"type":"object","properties":{"google":{"type":"string"},"outlook":{"type":"string"},"office365":{"type":"string"},"apple":{"type":"string"}},"required":["google","outlook","office365","apple"],"additionalProperties":false},"event_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","mode","name","description","timezone","site_url","language","default_duration","brand_color","organizer","show_events","blocked","logo_url","banner_url","subscribe_page_url","feed_url","subscribe_links","event_count","created_at","updated_at"],"additionalProperties":false}}}}}},"get":{"summary":"List calendars","tags":["Publisher"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"mode":{"type":"string","enum":["live","test"]},"name":{"type":"string"},"description":{"type":["string","null"]},"timezone":{"type":"string"},"site_url":{"type":["string","null"]},"language":{"type":"string","enum":["en","de"]},"default_duration":{"type":"string"},"brand_color":{"type":["string","null"]},"organizer":{"type":["object","null"],"properties":{"name":{"type":"string"},"url":{"type":["string","null"]},"email":{"type":["string","null"]}},"required":["name","url","email"],"additionalProperties":false},"show_events":{"type":"boolean"},"blocked":{"type":"boolean"},"logo_url":{"type":["string","null"]},"banner_url":{"type":["string","null"]},"subscribe_page_url":{"type":"string"},"feed_url":{"type":"string"},"subscribe_links":{"type":"object","properties":{"google":{"type":"string"},"outlook":{"type":"string"},"office365":{"type":"string"},"apple":{"type":"string"}},"required":["google","outlook","office365","apple"],"additionalProperties":false},"event_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","mode","name","description","timezone","site_url","language","default_duration","brand_color","organizer","show_events","blocked","logo_url","banner_url","subscribe_page_url","feed_url","subscribe_links","event_count","created_at","updated_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/v1/publisher/calendars/{calendar_id}":{"get":{"summary":"Get a calendar","tags":["Publisher"],"parameters":[{"schema":{"type":"string","maxLength":64},"in":"path","name":"calendar_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"mode":{"type":"string","enum":["live","test"]},"name":{"type":"string"},"description":{"type":["string","null"]},"timezone":{"type":"string"},"site_url":{"type":["string","null"]},"language":{"type":"string","enum":["en","de"]},"default_duration":{"type":"string"},"brand_color":{"type":["string","null"]},"organizer":{"type":["object","null"],"properties":{"name":{"type":"string"},"url":{"type":["string","null"]},"email":{"type":["string","null"]}},"required":["name","url","email"],"additionalProperties":false},"show_events":{"type":"boolean"},"blocked":{"type":"boolean"},"logo_url":{"type":["string","null"]},"banner_url":{"type":["string","null"]},"subscribe_page_url":{"type":"string"},"feed_url":{"type":"string"},"subscribe_links":{"type":"object","properties":{"google":{"type":"string"},"outlook":{"type":"string"},"office365":{"type":"string"},"apple":{"type":"string"}},"required":["google","outlook","office365","apple"],"additionalProperties":false},"event_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","mode","name","description","timezone","site_url","language","default_duration","brand_color","organizer","show_events","blocked","logo_url","banner_url","subscribe_page_url","feed_url","subscribe_links","event_count","created_at","updated_at"],"additionalProperties":false}}}}}},"patch":{"summary":"Update a calendar","tags":["Publisher"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":["string","null"],"maxLength":1000},"timezone":{"type":"string"},"site_url":{"type":["string","null"],"maxLength":2000},"language":{"type":"string","enum":["en","de"]},"default_duration":{"type":"string"},"brand_color":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$"},"organizer":{"type":["object","null"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"url":{"type":["string","null"],"maxLength":2000},"email":{"type":["string","null"],"format":"email","maxLength":254}},"required":["name"],"additionalProperties":false},"show_events":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","maxLength":64},"in":"path","name":"calendar_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"mode":{"type":"string","enum":["live","test"]},"name":{"type":"string"},"description":{"type":["string","null"]},"timezone":{"type":"string"},"site_url":{"type":["string","null"]},"language":{"type":"string","enum":["en","de"]},"default_duration":{"type":"string"},"brand_color":{"type":["string","null"]},"organizer":{"type":["object","null"],"properties":{"name":{"type":"string"},"url":{"type":["string","null"]},"email":{"type":["string","null"]}},"required":["name","url","email"],"additionalProperties":false},"show_events":{"type":"boolean"},"blocked":{"type":"boolean"},"logo_url":{"type":["string","null"]},"banner_url":{"type":["string","null"]},"subscribe_page_url":{"type":"string"},"feed_url":{"type":"string"},"subscribe_links":{"type":"object","properties":{"google":{"type":"string"},"outlook":{"type":"string"},"office365":{"type":"string"},"apple":{"type":"string"}},"required":["google","outlook","office365","apple"],"additionalProperties":false},"event_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","mode","name","description","timezone","site_url","language","default_duration","brand_color","organizer","show_events","blocked","logo_url","banner_url","subscribe_page_url","feed_url","subscribe_links","event_count","created_at","updated_at"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete a calendar","tags":["Publisher"],"parameters":[{"schema":{"type":"string","maxLength":64},"in":"path","name":"calendar_id","required":true}],"responses":{"204":{"description":"No content","content":{"application/json":{"schema":{"enum":["null"],"description":"No content"}}}}}}},"/v1/publisher/calendars/{calendar_id}/images/{kind}":{"put":{"summary":"Upload the logo or banner","tags":["Publisher"],"description":"PNG, JPEG or WebP as the raw request body. Logo up to 512 KB (square, at least 192 px), banner up to 2 MB (about 3:1, at least 1200 px wide).","parameters":[{"schema":{"type":"string","maxLength":64},"in":"path","name":"calendar_id","required":true},{"schema":{"type":"string","enum":["logo","banner"]},"in":"path","name":"kind","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"mode":{"type":"string","enum":["live","test"]},"name":{"type":"string"},"description":{"type":["string","null"]},"timezone":{"type":"string"},"site_url":{"type":["string","null"]},"language":{"type":"string","enum":["en","de"]},"default_duration":{"type":"string"},"brand_color":{"type":["string","null"]},"organizer":{"type":["object","null"],"properties":{"name":{"type":"string"},"url":{"type":["string","null"]},"email":{"type":["string","null"]}},"required":["name","url","email"],"additionalProperties":false},"show_events":{"type":"boolean"},"blocked":{"type":"boolean"},"logo_url":{"type":["string","null"]},"banner_url":{"type":["string","null"]},"subscribe_page_url":{"type":"string"},"feed_url":{"type":"string"},"subscribe_links":{"type":"object","properties":{"google":{"type":"string"},"outlook":{"type":"string"},"office365":{"type":"string"},"apple":{"type":"string"}},"required":["google","outlook","office365","apple"],"additionalProperties":false},"event_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","mode","name","description","timezone","site_url","language","default_duration","brand_color","organizer","show_events","blocked","logo_url","banner_url","subscribe_page_url","feed_url","subscribe_links","event_count","created_at","updated_at"],"additionalProperties":false}}}}}},"delete":{"summary":"Remove the logo or banner","tags":["Publisher"],"parameters":[{"schema":{"type":"string","maxLength":64},"in":"path","name":"calendar_id","required":true},{"schema":{"type":"string","enum":["logo","banner"]},"in":"path","name":"kind","required":true}],"responses":{"204":{"description":"No content","content":{"application/json":{"schema":{"enum":["null"],"description":"No content"}}}}}}},"/v1/publisher/calendars/{calendar_id}/events/{external_id}":{"put":{"summary":"Create or update an event","tags":["Publisher"],"description":"Safe to retry. An unchanged event answers 200 with \"changed\": false and notifies nobody.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":65536},"location":{"type":"string","maxLength":500},"url":{"type":"string","maxLength":2000},"start":{"type":"string"},"end":{"type":"string"},"timezone":{"type":"string","maxLength":64},"all_day":{"type":"boolean"},"recurrence":{"type":"object","properties":{"rules":{"type":"array","items":{"type":"string","maxLength":500},"minItems":1,"maxItems":5},"except_dates":{"type":"array","items":{"type":"string"},"maxItems":1000},"overrides":{"type":"array","items":{"type":"object","properties":{"original_start":{"type":"string"},"start":{"type":"string"},"end":{"type":"string"},"title":{"type":"string","maxLength":255},"description":{"type":"string","maxLength":65536},"location":{"type":"string","maxLength":500},"url":{"type":"string","maxLength":2000},"status":{"type":"string","enum":["confirmed","tentative","cancelled"]}},"required":["original_start"],"additionalProperties":false},"maxItems":500}},"required":["rules"],"additionalProperties":false},"status":{"type":"string","enum":["confirmed","tentative","cancelled"]},"show_as":{"type":"string","enum":["free","busy"]},"categories":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"maxItems":10},"metadata":{"type":"object","additionalProperties":{}}},"required":["title","start"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","maxLength":64},"in":"path","name":"calendar_id","required":true},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"},"in":"path","name":"external_id","required":true},{"schema":{"type":"string","pattern":"^\"?\\d+\"?$"},"in":"header","name":"if-match","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"external_id":{"type":"string"},"calendar_id":{"type":"string"},"sequence":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"event":{"type":"object","additionalProperties":{}},"changed":{"type":"boolean"}},"required":["external_id","calendar_id","sequence","created_at","updated_at","event","changed"],"additionalProperties":false}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"external_id":{"type":"string"},"calendar_id":{"type":"string"},"sequence":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"event":{"type":"object","additionalProperties":{}},"changed":{"type":"boolean"}},"required":["external_id","calendar_id","sequence","created_at","updated_at","event","changed"],"additionalProperties":false}}}}}},"get":{"summary":"Get an event","tags":["Publisher"],"parameters":[{"schema":{"type":"string","maxLength":64},"in":"path","name":"calendar_id","required":true},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"},"in":"path","name":"external_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"external_id":{"type":"string"},"calendar_id":{"type":"string"},"sequence":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"event":{"type":"object","additionalProperties":{}}},"required":["external_id","calendar_id","sequence","created_at","updated_at","event"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete an event","tags":["Publisher"],"description":"Always 204, also when the event was already gone.","parameters":[{"schema":{"type":"string","maxLength":64},"in":"path","name":"calendar_id","required":true},{"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"},"in":"path","name":"external_id","required":true}],"responses":{"204":{"description":"No content","content":{"application/json":{"schema":{"enum":["null"],"description":"No content"}}}}}}},"/v1/publisher/calendars/{calendar_id}/events":{"get":{"summary":"List events","tags":["Publisher"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","maxLength":500},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"updated_since","required":false},{"schema":{"type":"string","maxLength":64},"in":"path","name":"calendar_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string"},"calendar_id":{"type":"string"},"sequence":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"event":{"type":"object","additionalProperties":{}}},"required":["external_id","calendar_id","sequence","created_at","updated_at","event"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}}}}},"/v1/publisher/calendars/{calendar_id}/events/batch":{"post":{"summary":"Up to 100 upserts and deletes in one call","tags":["Publisher"],"description":"Operations are applied in order; one failing item does not stop the others.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operations":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"method":{"type":"string","enum":["PUT"]},"external_id":{"type":"string"},"event":{}},"required":["method","external_id"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","enum":["DELETE"]},"external_id":{"type":"string"}},"required":["method","external_id"],"additionalProperties":false}]},"minItems":1,"maxItems":100},"sync_id":{"type":"string","maxLength":64}},"required":["operations"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","maxLength":64},"in":"path","name":"calendar_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["results"],"additionalProperties":false}}}}}}},"/v1/publisher/calendars/{calendar_id}/stats":{"get":{"summary":"Subscriber counts","tags":["Publisher"],"description":"A feed subscriber counts while their calendar app fetched the feed in the last 14 days. subscribe_clicks_30d counts every pick in the app menu of the subscribe page and the embedded button, fetched or not. plan shows the account against its plan (plan business = Professional); going over the subscriber limit never stops a feed.","parameters":[{"schema":{"type":"string","maxLength":64},"in":"path","name":"calendar_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"as_of":{"type":"string"},"subscribers":{"type":"object","properties":{"total":{"type":"number"},"feed":{"type":"object","properties":{"total":{"type":"number"},"by_app":{"type":"object","additionalProperties":{"type":"number"}}},"required":["total","by_app"],"additionalProperties":false},"live":{"type":"object","properties":{"total":{"type":"number"},"by_provider":{"type":"object","additionalProperties":{"type":"number"}}},"required":["total","by_provider"],"additionalProperties":false}},"required":["total","feed","live"],"additionalProperties":false},"direct_feed_clients_7d":{"type":["number","null"]},"subscribe_clicks_30d":{"type":"object","properties":{"total":{"type":"number"},"by_app":{"type":"object","additionalProperties":{"type":"number"}}},"required":["total","by_app"],"additionalProperties":false},"plan":{"type":"object","properties":{"plan":{"type":"string","enum":["free","basic","business"]},"live_calendars":{"type":"object","properties":{"used":{"type":"number"},"limit":{"type":"number"}},"required":["used","limit"],"additionalProperties":false},"active_subscribers":{"type":"object","properties":{"used":{"type":"number"},"limit":{"type":"number"}},"required":["used","limit"],"additionalProperties":false},"over_calendar_limit":{"type":"boolean"},"over_subscriber_limit":{"type":"boolean"}},"required":["plan","live_calendars","active_subscribers","over_calendar_limit","over_subscriber_limit"],"additionalProperties":false}},"required":["as_of","subscribers","direct_feed_clients_7d","subscribe_clicks_30d","plan"],"additionalProperties":false}}}}}}},"/v1/publisher/calendars/{calendar_id}/syncs":{"post":{"summary":"Start a full sync","tags":["Publisher"],"parameters":[{"schema":{"type":"string","maxLength":64},"in":"path","name":"calendar_id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"sync_id":{"type":"string"},"expires_at":{"type":"string"}},"required":["sync_id","expires_at"],"additionalProperties":false}}}}}}},"/v1/publisher/calendars/{calendar_id}/syncs/{sync_id}/complete":{"post":{"summary":"Finish a full sync","tags":["Publisher"],"description":"Removes every event not sent during the sync. Refuses with 409 large_delete above half the calendar.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"not":{}},{"type":["object","null"],"properties":{"confirm_large_delete":{"type":"boolean"}},"additionalProperties":false}]}}}},"parameters":[{"schema":{"type":"string","maxLength":64},"in":"path","name":"calendar_id","required":true},{"schema":{"type":"string","maxLength":64},"in":"path","name":"sync_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"sync_id":{"type":"string"},"deleted":{"type":"number"},"remaining":{"type":"number"}},"required":["sync_id","deleted","remaining"],"additionalProperties":false}}}}}}}},"servers":[{"url":"https://api.kalender-sync.de"}],"security":[{"apiKey":[]}]}