---
title: "Calendar API"
url: "https://developers.rest.rodeo/apis/calendar/versions/9fa518e1-4597-4801-ad08-2c360cda2316"
---

# Calendar API

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Calendar API","description":"Manages calendars and their events. Consumers must create a calendar before adding events. Events may be all-day (no times) or time-bound. The billing profile is a subscription with no limits.","version":"1.0.0"},"servers":[{"url":"https://api.rest.rodeo/calendar/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"paths":{"/calendars":{"get":{"operationId":"listCalendars","summary":"/calendars","description":"Lists every calendar.","responses":{"200":{"description":"All calendars","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarsList"},"examples":{"calendars":{"value":{"calendars":[{"id":"3d8df2a2-0d68-4dc4-9d5e-6b1e94a7a51d","name":"Work"}]}}}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createCalendar","summary":"/calendars","description":"Creates a calendar.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarRequest"},"examples":{"create":{"value":{"name":"Work"}}}}}},"responses":{"201":{"description":"The created calendar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Calendar"},"examples":{"calendar":{"value":{"id":"3d8df2a2-0d68-4dc4-9d5e-6b1e94a7a51d","name":"Work"}}}}}},"400":{"description":"Invalid JSON body or invalid `name`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/calendars/{calendarId}":{"get":{"operationId":"getCalendar","summary":"/calendars/{calendarId}","description":"Returns a single calendar by id.","parameters":[{"$ref":"#/components/parameters/CalendarId"}],"responses":{"200":{"description":"The calendar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Calendar"},"examples":{"calendar":{"value":{"id":"3d8df2a2-0d68-4dc4-9d5e-6b1e94a7a51d","name":"Work"}}}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No calendar with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"updateCalendar","summary":"/calendars/{calendarId}","description":"Replaces the calendar's name.","parameters":[{"$ref":"#/components/parameters/CalendarId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarRequest"},"examples":{"update":{"value":{"name":"Personal"}}}}}},"responses":{"200":{"description":"The updated calendar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Calendar"},"examples":{"calendar":{"value":{"id":"3d8df2a2-0d68-4dc4-9d5e-6b1e94a7a51d","name":"Personal"}}}}}},"400":{"description":"Invalid JSON body or invalid `name`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No calendar with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteCalendar","summary":"/calendars/{calendarId}","description":"Deletes the calendar and all of its events.","parameters":[{"$ref":"#/components/parameters/CalendarId"}],"responses":{"204":{"description":"The calendar was deleted"},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No calendar with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/calendars/{calendarId}/events":{"get":{"operationId":"listEvents","summary":"/calendars/{calendarId}/events","description":"Lists every event in the calendar.","parameters":[{"$ref":"#/components/parameters/CalendarId"}],"responses":{"200":{"description":"All events in the calendar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsList"},"examples":{"events":{"value":{"events":[{"id":"9f6f7c7a-88f3-4f42-a3f3-4b41d63b325a","calendarId":"3d8df2a2-0d68-4dc4-9d5e-6b1e94a7a51d","title":"Rodeo kickoff","description":"Season opener","startDate":"2026-10-01","endDate":"2026-10-01","startTime":"18:00","endTime":"21:00","allDay":false}]}}}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No calendar with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createEvent","summary":"/calendars/{calendarId}/events","description":"Creates an event in the calendar. When `allDay` is true, `startTime` and `endTime` must be null; otherwise both are required.","parameters":[{"$ref":"#/components/parameters/CalendarId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventRequest"},"examples":{"timed":{"value":{"title":"Rodeo kickoff","description":"Season opener","startDate":"2026-10-01","endDate":"2026-10-01","startTime":"18:00","endTime":"21:00","allDay":false}},"allDay":{"value":{"title":"Rodeo finals","description":"Championship day","startDate":"2026-10-15","endDate":"2026-10-16","startTime":null,"endTime":null,"allDay":true}}}}}},"responses":{"201":{"description":"The created event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"},"examples":{"event":{"value":{"id":"9f6f7c7a-88f3-4f42-a3f3-4b41d63b325a","calendarId":"3d8df2a2-0d68-4dc4-9d5e-6b1e94a7a51d","title":"Rodeo kickoff","description":"Season opener","startDate":"2026-10-01","endDate":"2026-10-01","startTime":"18:00","endTime":"21:00","allDay":false}}}}}},"400":{"description":"Invalid JSON body or invalid event fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No calendar with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/calendars/{calendarId}/events/{eventId}":{"get":{"operationId":"getEvent","summary":"/calendars/{calendarId}/events/{eventId}","description":"Returns a single event by id.","parameters":[{"$ref":"#/components/parameters/CalendarId"},{"$ref":"#/components/parameters/EventId"}],"responses":{"200":{"description":"The event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"},"examples":{"event":{"value":{"id":"9f6f7c7a-88f3-4f42-a3f3-4b41d63b325a","calendarId":"3d8df2a2-0d68-4dc4-9d5e-6b1e94a7a51d","title":"Rodeo kickoff","description":"Season opener","startDate":"2026-10-01","endDate":"2026-10-01","startTime":"18:00","endTime":"21:00","allDay":false}}}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No calendar or event with these ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"updateEvent","summary":"/calendars/{calendarId}/events/{eventId}","description":"Replaces the event. All fields are required.","parameters":[{"$ref":"#/components/parameters/CalendarId"},{"$ref":"#/components/parameters/EventId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventRequest"},"examples":{"update":{"value":{"title":"Rodeo kickoff","description":"Season opener, moved","startDate":"2026-10-01","endDate":"2026-10-02","startTime":"19:00","endTime":"22:00","allDay":false}}}}}},"responses":{"200":{"description":"The updated event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"},"examples":{"event":{"value":{"id":"9f6f7c7a-88f3-4f42-a3f3-4b41d63b325a","calendarId":"3d8df2a2-0d68-4dc4-9d5e-6b1e94a7a51d","title":"Rodeo kickoff","description":"Season opener, moved","startDate":"2026-10-01","endDate":"2026-10-02","startTime":"19:00","endTime":"22:00","allDay":false}}}}}},"400":{"description":"Invalid JSON body or invalid event fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No calendar or event with these ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteEvent","summary":"/calendars/{calendarId}/events/{eventId}","description":"Deletes the event.","parameters":[{"$ref":"#/components/parameters/CalendarId"},{"$ref":"#/components/parameters/EventId"}],"responses":{"204":{"description":"The event was deleted"},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No calendar or event with these ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"parameters":{"CalendarId":{"name":"calendarId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The calendar id."},"EventId":{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The event id."}},"schemas":{"Calendar":{"type":"object","required":["id","name"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The calendar id."},"name":{"type":"string","description":"The calendar name.","maxLength":256}}},"CalendarRequest":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"The calendar name.","maxLength":256,"minLength":1}}},"CalendarsList":{"type":"object","required":["calendars"],"additionalProperties":false,"properties":{"calendars":{"type":"array","items":{"$ref":"#/components/schemas/Calendar"}}}},"Event":{"type":"object","required":["id","calendarId","title","description","startDate","endDate","startTime","endTime","allDay"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The event id."},"calendarId":{"type":"string","format":"uuid","description":"The id of the calendar this event belongs to."},"title":{"type":"string","description":"The event title.","maxLength":256},"description":{"type":"string","description":"The event description.","maxLength":2000},"startDate":{"type":"string","description":"The date the event starts.","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-10-01"},"endDate":{"type":"string","description":"The date the event ends. Must not be before `startDate`.","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-10-01"},"startTime":{"type":"string","nullable":true,"description":"The time the event starts. Null when `allDay` is true.","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","example":"18:00"},"endTime":{"type":"string","nullable":true,"description":"The time the event ends. Null when `allDay` is true.","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","example":"21:00"},"allDay":{"type":"boolean","description":"Whether the event lasts all day. When true, `startTime` and `endTime` must be null; otherwise both are required."}}},"EventRequest":{"type":"object","required":["title","description","startDate","endDate","startTime","endTime","allDay"],"additionalProperties":false,"properties":{"title":{"type":"string","description":"The event title.","maxLength":256,"minLength":1},"description":{"type":"string","description":"The event description.","maxLength":2000},"startDate":{"type":"string","description":"The date the event starts.","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-10-01"},"endDate":{"type":"string","description":"The date the event ends. Must not be before `startDate`.","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-10-01"},"startTime":{"type":"string","nullable":true,"description":"The time the event starts. Required null when `allDay` is true, required non-null otherwise.","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","example":"18:00"},"endTime":{"type":"string","nullable":true,"description":"The time the event ends. Required null when `allDay` is true, required non-null otherwise.","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","example":"21:00"},"allDay":{"type":"boolean","description":"Whether the event lasts all day."}}},"EventsList":{"type":"object","required":["events"],"additionalProperties":false,"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}},"Error":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string"}}}}}}
```