Subscription calendars for developers

A developer project maintains subscription calendars with its app token at https://api.getridian.com/v1/public-calendars. Turn access on under Developer > API projects, Access tab; API at the top of a subscription calendar page shows the status and links there. The switch applies to the whole project: it can then read and change all subscription calendars of the workspace. Events from the API show the source “API” in the console and can still be edited there.

REST API

Method and path	Scope	Purpose
GET /public-calendars	public_calendars:read	Calendars of the workspace
POST /public-calendars	public_calendars:write	Create a calendar; mode is test (default) or live
GET, PATCH, DELETE /public-calendars/{id}	read or write	Read, change or delete a calendar
GET /public-calendars/{id}/events	public_calendars:read	Events, paginated
GET, PUT, DELETE /public-calendars/{id}/events/{external_id}	read or write	Read, create or replace, delete an event by your own ID
POST /public-calendars/{id}/events/batch	public_calendars:write	Many events in one call (operations)
POST /public-calendars/{id}/syncs and …/syncs/{sync_id}/complete	public_calendars:write	Full sync: whatever the sync did not include is deleted
PUT, DELETE /public-calendars/{id}/images/logo or /banner	public_calendars:write	Logo and banner
GET /public-calendars/{id}/stats	public_calendars:read	Active and new subscriptions

Address events by your own external_id; a PUT with the same ID replaces the event instead of creating a second one. Send an Idempotency-Key when creating a calendar so a retry returns the same calendar. Errors are Problem Details (RFC 9457) with a code.

Full sync: Start a sync, write all current events with sync_id through events/batch and finish with complete. Events missing from the sync are deleted. If that would delete a large number of events, complete asks for confirm_large_delete: true.

curl -X PUT https://api.getridian.com/v1/public-calendars/$CALENDAR/events/class-2027-01-12 \
  -H "Authorization: Bearer $RIDIAN_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Evening yoga","start":"2027-01-12T18:00:00+01:00","end":"2027-01-12T19:30:00+01:00","timezone":"Europe/Berlin"}'

Webhooks

Under Developer > Webhooks you add up to five webhooks per developer project, to a public https address. Events:

• subscriber.created: a new subscription fetched the calendar for the first time.
• calendar.updated: events or settings changed. Several changes in quick succession arrive as one message with the current state.

Every delivery carries x-ridian-event, x-ridian-delivery, x-ridian-timestamp and x-ridian-signature: v1=<HMAC-SHA256> over <timestamp>.<body> using the webhook’s secret. You only see the secret when you create the webhook. If your server does not answer with 2xx, we retry after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours. Developer > Webhooks lists all webhooks of the workspace with a delivery log: event, time, HTTP status or error reason and next attempt. We delete deliveries 30 days after delivery or after the last attempt.

Assistants

With the scopes public_calendars:read and public_calendars:write, MCP clients can read and maintain subscription calendars in conversation as well. There too, only admins and owners can make changes.