Events
/api/calendar/{calendarId}/events
Exposes stored calendar events and stages event changes until commit.
GET /api/calendar/{calendarId}/events
Lists expanded events in the requested half-open interval.
Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
calendarId |
path | string |
yes | calendar identifier from the request path |
from |
query | string (date-time) |
no | optional ISO-8601 interval start |
to |
query | string (date-time) |
no | optional ISO-8601 interval end |
fields |
query | string |
no | Comma-separated readable properties to include in the JSON response. |
format |
query | string [ics] |
no | — |
Response
| Status | Content Type | Schema | Description |
|---|---|---|---|
200 |
application/json |
array<CalendarEventRead> |
events overlapping [from, to) |
200 |
text/calendar |
string |
events overlapping [from, to) |
Example Request
# Request
GET /api/calendar/<calendarId>/events HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>
# Response
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"attachments": [
"string"
],
"recurrence": "string",
"id": "6q95hc9lvm8vcr7xh8zkh49ie",
"masterId": "0rjcg9jmvusb5ijzqoz8i3txf",
"recurrenceId": 0
}
]
Example Request - ICS
# Request GET /api/calendar/<calendarId>/events?format=ics HTTP/1.1 Accept: text/calendar Authorization: Bearer <access-token> # Response HTTP/1.1 200 OK Content-Type: text/calendar BEGIN:VCALENDAR ... END:VCALENDAR
POST /api/calendar/{calendarId}/events
Creates a staged event below a resolved calendar.
Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
calendarId |
path | string |
yes | calendar identifier from the request path |
Request Body
| Content Type | Schema | Required | Description |
|---|---|---|---|
application/json |
CalendarEventCreate |
yes | — |
Response
| Status | Content Type | Schema | Description |
|---|---|---|---|
201 |
application/json |
CalendarEventRead |
new staged event |
Example Request
# Request
POST /api/calendar/<calendarId>/events HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>
Content-Type: application/json
{
"attachments": [
"string"
],
"recurrence": "string",
"summary": "string",
"description": "string",
"location": "string"
}
# Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"attachments": [
"string"
],
"recurrence": "string",
"id": "6q95hc9lvm8vcr7xh8zkh49ie",
"masterId": "0rjcg9jmvusb5ijzqoz8i3txf",
"recurrenceId": 0
}
Common Error Responses
The status codes 400, 403, 404, 405, 406, 409, 413, 415, and 500 use the same ApiError JSON error format:
{
"status": 404,
"code": "route_not_found",
"message": "The requested API route does not exist.",
"details": []
}
Schemas
Request and response schemas used on this page.
CalendarEventRead
| Property | Type | Required | Description |
|---|---|---|---|
attachments |
array<string> |
no |
Returns attachment URLs without exposing internal attachment metadata. |
recurrence |
EventRecurrence |
no |
Optional recurrence rule and exception data. |
id |
string |
no |
Current internal event identifier. |
masterId |
string |
no |
Current series master identifier for an expanded occurrence. |
recurrenceId |
number (int64) |
no |
Original start of the replaced occurrence as Unix epoch milliseconds (RFC 5545 |
uid |
string |
no |
External iCalendar UID, which is not used for routing. |
summary |
string |
no |
Event title. |
description |
string |
no |
Optional event description. |
location |
string |
no |
Optional event location. |
startTime |
number (int64) |
no |
Start instant as Unix epoch milliseconds. |
endTime |
number (int64) |
no |
End instant as Unix epoch milliseconds. |
allDay |
boolean |
no |
Whether the event spans whole local calendar days. |
timezone |
string |
no |
IANA timezone used for local and recurring event semantics. |
attendees |
array<Attendee> |
no |
Event attendees and their response states. |
priority |
integer (int32) |
no |
Event priority from zero through nine. |
url |
string |
no |
Optional related URL. |
categories |
array<string> |
no |
Event category names. |
color |
string |
no |
Optional event-specific color. |
reminders |
array<Reminder> |
no |
Reminder alarms. |
transparent |
boolean |
no |
Whether the event is transparent for free/busy calculations. |
status |
string [TENTATIVE, CONFIRMED, CANCELLED] |
no |
Current iCalendar event status. |
sequence |
integer (int32) |
no |
Monotonic iCalendar sequence value. |
immutable |
boolean |
no |
Whether the provider marks the event as immutable. |
created |
number (int64) |
no |
Event creation time as Unix epoch milliseconds. |
lastModified |
number (int64) |
no |
Last modification time as Unix epoch milliseconds. |
attachmentEditingEnabled |
boolean |
no |
Whether the target provider supports changing attachment URLs. |
EventRecurrence
| Property | Type | Required | Description |
|---|---|---|---|
rrule |
string |
no | — |
exdate |
array<number (int64)> |
no | — |
rdate |
array<number (int64)> |
no | — |
until |
number (int64) |
no | — |
overridden |
array<number (int64)> |
no | — |
Attendee
| Property | Type | Required | Description |
|---|---|---|---|
name |
string |
no | — |
email |
string |
no | — |
status |
string [NONE, ACCEPTED, DECLINED, TENTATIVE] |
no | — |
Reminder
| Property | Type | Required | Description |
|---|---|---|---|
before |
number (int64) |
no | — |
description |
string |
no | — |
type |
string [DISPLAY, EMAIL] |
no | — |
ApiError
| Property | Type | Required | Description |
|---|---|---|---|
status |
integer (int32) |
yes | — |
code |
string |
yes | — |
message |
string |
yes | — |
details |
array<object> |
no | — |
CalendarEventCreate
| Property | Type | Required | Description |
|---|---|---|---|
attachments |
array<string> |
no |
Replaces, clears, or resets attachment URLs. |
recurrence |
EventRecurrence |
no |
Replaces or clears recurrence data while normalizing omitted date collections. |
summary |
string |
no |
Event title. |
description |
string |
no |
Optional event description. |
location |
string |
no |
Optional event location. |
startTime |
number (int64) |
no |
Start instant as Unix epoch milliseconds. |
endTime |
number (int64) |
no |
End instant as Unix epoch milliseconds. |
allDay |
boolean |
no |
Whether the event spans whole local calendar days. |
timezone |
string |
no |
IANA timezone used for local and recurring event semantics. |
attendees |
array<Attendee> |
no |
Event attendees and their response states. |
priority |
integer (int32) |
no |
Event priority from zero through nine. |
url |
string |
no |
Optional related URL. |
categories |
array<string> |
no |
Event category names. |
color |
string |
no |
Optional event-specific color. |
reminders |
array<Reminder> |
no |
Reminder alarms. |
transparent |
boolean |
no |
Whether the event is transparent for free/busy calculations. |
status |
string [TENTATIVE, CONFIRMED, CANCELLED] |
no |
Current iCalendar event status. |