# AddCal API Documentation

The official AddCal API documentation. This comprehensive guide provides developers with everything needed to integrate calendar and event management functionality into their applications. Our RESTful API enables seamless creation, management, and sharing of events across multiple platforms and calendar services.

- Base URL: `https://addcal.co`
- Authentication: HTTP Bearer token. You can retrieve your token from the [API Tokens page](https://addcal.co/user/api-tokens) in your dashboard.
- OpenAPI document: https://addcal.co/docs.openapi
- Interactive reference: https://addcal.co/docs

Send the token on every request:

```
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
```

## Sections

- [Create Event](https://addcal.co/docs/create-event.md)
- [Calendars](https://addcal.co/docs/calendars.md)
- [Events](https://addcal.co/docs/events.md)
- [Events > RSVPs](https://addcal.co/docs/rsvps.md)
- [Events > Invites](https://addcal.co/docs/invites.md)
- [Account](https://addcal.co/docs/account.md)
- [Dynamic Links](https://addcal.co/docs/dynamic-links.md)

## Dynamic Links

Generate add-to-calendar redirect URLs from query parameters. Requires a Dynamic Link Key (Business plan). The user is redirected to their chosen calendar service with the event pre-filled.

### /api/dyn

`GET /api/dyn`

**Query parameters**

- `uid` (string, required): Your Dynamic Link Key identifier.
- `service` (string, required): Calendar service to redirect to. Accepted: google, apple, outlook, outlook_web, office365, yahoo, ics, manual.
- `title` (string, required): Event title. Max 255 characters.
- `start` (string, required): Start date/time in ISO 8601 format.
- `end` (string, optional): End date/time in ISO 8601 format. Defaults to 1 hour after start if omitted.
- `duration` (integer, optional): Duration in minutes. Takes precedence over end.
- `timezone` (string, optional): IANA timezone. Required for timed events.
- `all_day_event` (boolean, optional): Set to true for all-day events.
- `description` (string, optional): Event description. Max 2000 characters.
- `location` (string, optional): Physical address or virtual meeting URL. Max 255 characters.
- `alarm` (integer, optional): Reminder in minutes before the event.
- `recurring` (string, optional): RFC 5545 recurrence rule (RRULE).
- `transp` (string, optional): Busy status: OPAQUE (busy) or TRANSPARENT (free). Defaults to OPAQUE.

**Body parameters** (`application/json`)

- `uid` (string, required): No description.
- `title` (string, required): Must not be greater than 255 characters.
- `start` (string, required): Must be a valid date.
- `end` (string, optional): Must be a valid date. Must be a date after or equal to start.
- `duration` (integer, optional): Must be at least 1.
- `all_day_event` (string, optional): No description.
- `timezone` (string, required): Must be a valid time zone, such as Africa/Accra.
- `description` (string, optional): Must not be greater than 2000 characters.
- `location` (string, optional): Must not be greater than 255 characters.
- `alarm` (integer, optional): Must be at least 0.
- `recurring` (string, optional): No description.
- `transp` (string, optional): No description. Options: `TRANSPARENT`, `OPAQUE`.
- `service` (string, optional): No description.

**Example request**

```bash
curl --request GET \
  --url 'https://addcal.co/api/dyn' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json'
```

**Response 302** — Redirects the user to the chosen calendar service with the event pre-filled.

**Response 403** — Team is not on the Business plan.

**Response 404**

**Response 422** — When validation fails (e.g. missing required params or unrecognised service).

```json
{
    "message": "The provided Dynamic Link parameters were invalid."
}
```

### /api/dyn_ade

`GET /api/dyn_ade`

**Query parameters**

- `client` (string, required): AddEvent compatibility alias for uid. Your Dynamic Link Key identifier.
- `service` (string, required): Calendar service to redirect to. AddEvent values (outlookcom, stream) are automatically mapped. Accepted: google, apple, outlook, outlook_web, office365, yahoo, ics, manual.
- `title` (string, required): Event title. Max 255 characters.
- `start` (string, required): Start date/time in ISO 8601 format.
- `end` (string, optional): End date/time in ISO 8601 format. Defaults to 1 hour after start if omitted.
- `duration` (integer, optional): Duration in minutes. Takes precedence over end.
- `timezone` (string, optional): IANA timezone. Required for timed events.
- `all_day_event` (boolean, optional): Set to true for all-day events.
- `description` (string, optional): Event description. Max 2000 characters.
- `location` (string, optional): Physical address or virtual meeting URL. Max 255 characters.
- `alarm` (integer, optional): Reminder in minutes before the event.
- `recurring` (string, optional): RFC 5545 recurrence rule (RRULE).
- `transp` (string, optional): Busy status: OPAQUE (busy) or TRANSPARENT (free). Defaults to OPAQUE.

**Body parameters** (`application/json`)

- `uid` (string, required): No description.
- `title` (string, required): Must not be greater than 255 characters.
- `start` (string, required): Must be a valid date.
- `end` (string, optional): Must be a valid date. Must be a date after or equal to start.
- `duration` (integer, optional): Must be at least 1.
- `all_day_event` (string, optional): No description.
- `timezone` (string, required): Must be a valid time zone, such as Africa/Accra.
- `description` (string, optional): Must not be greater than 2000 characters.
- `location` (string, optional): Must not be greater than 255 characters.
- `alarm` (integer, optional): Must be at least 0.
- `recurring` (string, optional): No description.
- `transp` (string, optional): No description. Options: `TRANSPARENT`, `OPAQUE`.
- `service` (string, optional): No description.

**Example request**

```bash
curl --request GET \
  --url 'https://addcal.co/api/dyn_ade' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json'
```

**Response 302** — Redirects the user to the chosen calendar service with the event pre-filled.

**Response 403** — Team is not on the Business plan.

**Response 404**

**Response 422** — When validation fails (e.g. missing required params or unrecognised service).

```json
{
    "message": "The provided Dynamic Link parameters were invalid."
}
```