REST API reference

Base URL and authorization

Use https://api.getridian.com/v1 with a delegated bearer token containing calendar:read. The same grant and content-policy checks apply as in MCP. The public OpenAPI document is currently a minimal read-interface description, not a complete partner SDK contract.

GET /calendars

Lists accessible calendars. Returns data with the calendar list and meta.excluded with exclusion information. Work with the returned opaque IDs; do not derive them from provider email addresses.

curl https://api.getridian.com/v1/calendars \
  -H "Authorization: Bearer $RIDIAN_ACCESS_TOKEN"

GET /events

Query parameter	Required	Meaning
calendar_id	Yes	One or more permitted calendar IDs; repeat the parameter or use comma-separated IDs
start	Yes	ISO timestamp with Z or an explicit offset
end	Yes	End of the requested window, with Z or offset
time_zone	For CalDAV without a known zone	User’s IANA zone, such as Europe/Berlin

The window is bounded to 20 calendars and 744 elapsed hours (31 × 24 hours). When daylight saving time ends, 31 local calendar days can span 745 hours. Split longer periods into consecutive windows; each window’s end is exclusive. The response wraps permitted events in data. canEdit and canRespond also reflect the token’s effective scopes; they are not provider permissions alone. When canEdit=false, editBlockedReason gives the verified reason, such as recurring_event, calendar_read_only or access_denied; unknown means the reason is not known. version_unavailable means the version needed for safe writing could not be verified. The optional calendar providerPreset identifies a recognized CalDAV service (apple for iCloud). This metadata does not grant additional access.

curl --get https://api.getridian.com/v1/events \
  -H "Authorization: Bearer $RIDIAN_ACCESS_TOKEN" \
  --data-urlencode "calendar_id=$RIDIAN_CALENDAR_ID" \
  --data-urlencode 'start=2026-10-25T00:00:00+02:00' \
  --data-urlencode 'end=2026-10-26T00:00:00+01:00' \
  --data-urlencode 'time_zone=Europe/Berlin'

Set token and calendar variables privately; never commit their values. These timestamps deliberately illustrate a 25-hour DST day. Choose a window appropriate for your own test.

Errors and unsupported operations

Invalid parameters return an error rather than an assumed timezone. A missing CalDAV zone uses time_zone_required. Authorization and server failures require their respective recovery path. See errors.

REST event creation, modification, deletion and a dedicated availability endpoint are part of planned developer work, not this published read contract. Use the supported MCP tools where appropriate; do not invent REST routes from tool names.