calendar-feeds

6 endpoints.

GET/api/users/me/calendar-feeds Bearer token

List the caller's calendar links

The caller's live calendar subscription links, newest first. The feed URLs themselves are never listed — only the last four characters of each (`token_hint`); a lost URL is replaced by creating a new link and revoking the old one. With include_revoked=true, the links revoked in the last 90 days follow. `can_include_team` says whether the caller may give a link a team scope.

Parameters

Name	In	Type	Required	Description
include_revoked	query	string	no	Set true to add the recently revoked links.

Responses

Status	Description	Body
200	The caller's calendar links.	CalendarFeedTokenList
400	A query parameter failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
500	The calendar links could not be read.	ErrorResponse

POST/api/users/me/calendar-feeds Bearer token

Create a calendar link

Creates a private calendar subscription link for the caller and returns its URL — the only response that ever will. Anyone holding the URL reads the feed (GET /calendar-feeds/{token}/calendar.ics) until the link is revoked, so hand it only to the calendar app subscribing to it. A team scope needs the caller to manage a role. A caller may hold 10 live links at once. A deployment can switch calendar feeds off (CALENDAR_FEEDS_ENABLED=false); no link can be created then.

Request body

application/jsonrequiredCreateCalendarFeedTokenRequest

Field	Type	Required	Description
label	string	yes	The owner's name for the link, to tell their calendars apart. 1–80 characters
scope	string	no	Defaults to self. one of "self" \| "team" \| "team_schedule"

Field

Type

Required

Description

label

string

yes

The owner's name for the link, to tell their calendars apart.

1–80 characters

scope

string

Defaults to self.

one of "self" | "team" | "team_schedule"

Responses

Status	Description	Body
201	The new link, with its URL and the ready-made subscribe links.	CreatedCalendarFeedToken
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	A team scope was asked for and the caller manages no role, or calendar feeds are turned off on this deployment.	ErrorResponse
409	The caller already holds 10 live links.	ErrorResponse
500	The calendar link could not be created.	ErrorResponse

POST/api/users/me/calendar-feeds/revoke-all Bearer token

Revoke every calendar link of the caller

Revokes all of the caller's live links at once — for a lost device, or a URL shared somewhere it should not have been when the caller cannot tell which. Every subscribed calendar stops updating; entries already synced stay until removed in each app.

Responses

Status	Description	Body
200	How many links were revoked; zero when there were none.	RevokeAllCalendarFeedTokensResponse
401	The access token is missing or invalid.	ErrorResponse
500	The calendar links could not be revoked.	ErrorResponse

PATCH/api/users/me/calendar-feeds/{feed_id} Bearer token

Rename or rescope a calendar link

Changes a live link's label or what it serves. The URL stays the same, so the calendar subscribed to it needs nothing redone: it picks the change up on its next fetch — which for Outlook can take hours. Switching to a team scope needs the caller to manage a role. A revoked link cannot be changed.

Parameters

Name	In	Type	Required	Description
feed_id	path	string (uuid)	yes	The link's id, from the caller's link listing.

Request body

application/jsonrequiredUpdateCalendarFeedTokenRequest

Field	Type	Required	Description
label	string	no	The owner's name for the link, to tell their calendars apart. 1–80 characters
scope	string	no	What the feed serves beyond the owner's own deadlines, training events and live quiz sittings. self: nothing more. team: plus their trainees' certification due dates. team_schedule: plus their trainees' due dates, training events and live quiz sittings. The team scopes need the owner to manage a role; while they manage none, a team link serves self content. one of "self" \| "team" \| "team_schedule"

Field

Type

Required

Description

label

string

The owner's name for the link, to tell their calendars apart.

1–80 characters

scope

string

What the feed serves beyond the owner's own deadlines, training events and live quiz sittings. self: nothing more. team: plus their trainees' certification due dates. team_schedule: plus their trainees' due dates, training events and live quiz sittings. The team scopes need the owner to manage a role; while they manage none, a team link serves self content.

one of "self" | "team" | "team_schedule"

Responses

Status	Description	Body
200	The updated link.	CalendarFeedToken
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	A team scope was asked for, and the caller manages no role.	ErrorResponse
404	The caller has no live link with that id.	ErrorResponse
500	The calendar link could not be updated.	ErrorResponse

DELETE/api/users/me/calendar-feeds/{feed_id} Bearer token

Revoke a calendar link

Revokes one of the caller's links: its URL stops serving at once. Entries a calendar app already synced stay there until the subscription is removed in that app. Revoking an already-revoked link changes nothing and answers 200.

Parameters

Name	In	Type	Required	Description
feed_id	path	string (uuid)	yes	The link's id, from the caller's link listing.

Responses

Status	Description	Body
200	The revoked link.	CalendarFeedToken
401	The access token is missing or invalid.	ErrorResponse
404	The caller has no link with that id.	ErrorResponse
500	The calendar link could not be revoked.	ErrorResponse

GET/api/calendar-feeds/{token}/calendar.ics Public

Read a calendar feed

The iCalendar (RFC 5545) feed a calendar app subscribes to: the link owner's certification deadlines, the training events they are on and the live quiz sittings they may sit — and, on a team link of an owner who manages a role, their trainees' due dates (team) or due dates, events and sittings (team_schedule). Evaluated afresh on every fetch. Authorized by the token in the path instead of a bearer token, so anyone holding the URL reads the feed until the link is revoked. HEAD answers the headers without building the feed.

Parameters

Name	In	Type	Required	Description
token	path	string	yes	The link's secret token, from the feed_url that POST /users/me/calendar-feeds returned when the link was created.

Responses

Status	Description	Body
200	The feed, as text/calendar.	—
404	No live link has that token, its owner is disabled, or feeds are turned off on this deployment — all alike.	ErrorResponse
500	The feed could not be built.	ErrorResponse