> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# On-call calendar feeds

> Make an iCalendar subscription address that puts a schedule, or the subscriber's own shifts across schedules, into a calendar app.

A calendar app (Google Calendar, Outlook, Apple Calendar and others) reads the subscription address. It
serves RFC 5545 iCalendar with the shifts from 30 days back to 90 days ahead, overrides and swaps included.
A feed covers either every shift of one schedule, or the subscriber's own shifts across schedules.

| Method and path | What it does | Permission |
| - | - | - |
| `GET /api/v1/schedules/calendar-feeds` | The current user's feeds. | `schedules.read` |
| `POST /api/v1/schedules/calendar-feeds` | Makes a subscription address. When the same schedule (or the personal feed) already has one, it is reset and the old address stops working at once. | `schedules.calendar_feeds.manage`, and `schedules.calendar_feeds.manage` on the schedule for a schedule feed |
| `DELETE /api/v1/schedules/calendar-feeds/{id}` | Stops one of the current user's feeds; its address stops working at once. | `schedules.calendar_feeds.manage` |
| `GET /api/v1/public/calendar/{token}.ics` | The address the calendar app reads, without signing in. | The token in the address |

## Make a subscription address

**Request body**

| Field | Type | Required | Notes |
| - | - | - | - |
| `schedule_id` | string | No | Subscribes to this schedule; leave it out for a personal feed. |

```bash cURL theme={null}
curl -X POST http://localhost:5080/api/v1/schedules/calendar-feeds \
  -H "authorization: Bearer $MS_TOKEN" \
  -H "content-type: application/json" \
  -d '{"schedule_id": "<schedule-id>"}'
```

```json 200 theme={null}
{
  "feed": {
    "id": "3KHtq0dYc1fUe8WnP2xLbR7aZsM",
    "schedule_id": "<schedule-id>",
    "schedule_name": "Payments primary",
    "created_at": 1790000000000000,
    "last_used_at": null
  },
  "path": "/api/v1/public/calendar/<token>.ics",
  "url": "https://molesignal.example.com/api/v1/public/calendar/<token>.ics"
}
```

The address is given only here, once; only the token's SHA-256 is stored. `url` is built from the
instance's external address and is `null` when none is set, in which case put `path` after the address
MoleSignal is reached at. Each feed in the list has `id`, `schedule_id`, `schedule_name`, `created_at` and
`last_used_at`, when a calendar last read it, but no address.

## How the calendar app reads it

```http theme={null}
GET /api/v1/public/calendar/{token}.ics
```

Every read checks the subscriber again: the account is still active, still in the organization and still
holds `schedules.read`, and for a schedule feed can still see that schedule. A failed check, a wrong token
or a stopped feed all return `404`. Shift titles and descriptions are in the subscriber's interface
language.

Anyone with the address can see these shifts; reset or stop the feed when it leaks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.