# REST API reference

The currently published read endpoints, parameters and response envelopes.

Source: https://docs.getridian.com/developers/rest/
Language: en
Reviewed: 2026-09-20

## 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](https://api.getridian.com/v1/openapi.json) 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.

```sh
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 31 days. The response wraps permitted events in `data`. `canEdit` and `canRespond` also reflect the token's effective scopes; they are not provider permissions alone.

```sh
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](https://docs.getridian.com/developers/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.