# 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) ## Calendars APIs for managing calendars ### List Calendars `GET /api/calendars` **Example request** ```bash curl --request GET \ --url 'https://addcal.co/api/calendars' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Accept: application/json' ``` **Response 200** ```json { "data": [ { "uid": "p9v02qsz079d", "public_id": "cal_p9v02qsz079d", "short_link": null, "name": "Test RSVP Cal", "internal_name": null, "description": "", "timezone": "Australia/Adelaide", "week_begins": 4, "public_url": "https://addcal.co/c/p9v02qsz079d", "upcoming_events_count": 3, "events_count": 71, "created_at": "2025-07-27T06:43:09.000000Z", "updated_at": "2025-11-18T03:43:23.000000Z" }, { "uid": "0vwbr1bxbjai", "public_id": "cal_0vwbr1bxbjai", "short_link": null, "name": "Test User's Calendar", "internal_name": null, "description": "

Professional meetings, webinars, and business events.

", "timezone": "Australia/Sydney", "week_begins": 1, "public_url": "https://addcal.co/c/0vwbr1bxbjai", "upcoming_events_count": 6, "events_count": 8, "created_at": "2025-07-29T23:32:49.000000Z", "updated_at": "2025-07-29T23:32:49.000000Z" }, { "uid": "moexypnt3wd4", "public_id": "cal_moexypnt3wd4", "short_link": null, "name": "Test User's Calendar", "internal_name": null, "description": "

Professional meetings, webinars, and business events.

", "timezone": "Australia/Sydney", "week_begins": 1, "public_url": "https://addcal.co/c/moexypnt3wd4", "upcoming_events_count": 0, "events_count": 0, "created_at": "2025-07-29T23:34:05.000000Z", "updated_at": "2025-07-29T23:34:05.000000Z" }, { "uid": "gvjtfhquosip", "public_id": "cal_gvjtfhquosip", "short_link": null, "name": "Test User's Calendar", "internal_name": null, "description": "

Personal events, family gatherings, and appointments.

", "timezone": "Australia/Sydney", "week_begins": 1, "public_url": "https://addcal.co/c/gvjtfhquosip", "upcoming_events_count": 0, "events_count": 252, "created_at": "2025-07-29T23:37:16.000000Z", "updated_at": "2025-07-29T23:37:16.000000Z" }, { "uid": "yxlbclyhg4e7", "public_id": "cal_yxlbclyhg4e7", "short_link": null, "name": "Test User's Tags", "internal_name": null, "description": "

Professional meetings, webinars, and business events.

", "timezone": "Australia/Sydney", "week_begins": 1, "public_url": "https://addcal.co/c/yxlbclyhg4e7", "upcoming_events_count": 0, "events_count": 13, "created_at": "2025-07-29T23:43:37.000000Z", "updated_at": "2025-08-23T05:25:01.000000Z" }, { "uid": "vj0wmxp7fo66", "public_id": "cal_vj0wmxp7fo66", "short_link": "test-cal", "name": "Recur test", "internal_name": null, "description": "", "timezone": "Australia/Sydney", "week_begins": 1, "public_url": "https://addcal.co/c/test-cal", "upcoming_events_count": 0, "events_count": 40, "created_at": "2025-09-07T00:12:49.000000Z", "updated_at": "2026-07-11T02:47:33.000000Z" }, { "uid": "irir0ggat1pc", "public_id": "cal_irir0ggat1pc", "short_link": null, "name": "Series", "internal_name": null, "description": "", "timezone": "Australia/Sydney", "week_begins": 1, "public_url": "https://addcal.co/c/irir0ggat1pc", "upcoming_events_count": 0, "events_count": 30, "created_at": "2025-09-17T02:17:41.000000Z", "updated_at": "2025-09-17T02:17:41.000000Z" }, { "uid": "vdp2pp652p6z", "public_id": "cal_vdp2pp652p6z", "short_link": null, "name": "Tag Filter Demo", "internal_name": null, "description": "

Seeded calendar for testing tag-filtered subscriptions.

", "timezone": "UTC", "week_begins": 1, "public_url": "https://addcal.co/c/vdp2pp652p6z", "upcoming_events_count": 3, "events_count": 9, "created_at": "2026-07-29T01:28:22.000000Z", "updated_at": "2026-07-31T04:22:27.000000Z" }, { "uid": "o5mn1flqqxo7", "public_id": "cal_o5mn1flqqxo7", "short_link": null, "name": "Tag Filter Demo (Require Info)", "internal_name": null, "description": "

Same tags, but gated behind the subscriber info form.

", "timezone": "UTC", "week_begins": 1, "public_url": "https://addcal.co/c/o5mn1flqqxo7", "upcoming_events_count": 0, "events_count": 3, "created_at": "2026-07-29T01:28:22.000000Z", "updated_at": "2026-07-29T02:49:17.000000Z" }, { "uid": "qr0d313df3vs", "public_id": "cal_qr0d313df3vs", "short_link": null, "name": "Tag Filter Demo (Opted Out)", "internal_name": null, "description": "

Tags exist but allow_tag_selection is off - control case.

", "timezone": "UTC", "week_begins": 1, "public_url": "https://addcal.co/c/qr0d313df3vs", "upcoming_events_count": 0, "events_count": 2, "created_at": "2026-07-29T01:28:22.000000Z", "updated_at": "2026-07-29T01:28:22.000000Z" }, { "uid": "4t0x0n0q6hvt", "public_id": "cal_4t0x0n0q6hvt", "short_link": null, "name": "vitae blanditiis rerum", "internal_name": "saepe eius ut", "description": "

Repudiandae quos suscipit similique saepe maiores. Omnis officiis qui placeat voluptates. Quia sunt corporis quis quasi harum in odio.

", "timezone": "UTC", "week_begins": 5, "public_url": "https://addcal.co/c/4t0x0n0q6hvt", "upcoming_events_count": 0, "events_count": 2, "created_at": "2026-07-31T06:19:21.000000Z", "updated_at": "2026-07-31T06:19:21.000000Z" }, { "uid": "hsr6p96ex40w", "public_id": "cal_hsr6p96ex40w", "short_link": null, "name": "rem quia maxime", "internal_name": null, "description": "

Cum optio dolor ducimus vitae enim. Consequatur perferendis velit non cum. Accusamus aut quidem dicta et numquam.

", "timezone": "UTC", "week_begins": 4, "public_url": "https://addcal.co/c/hsr6p96ex40w", "upcoming_events_count": 2, "events_count": 4, "created_at": "2026-07-31T06:25:45.000000Z", "updated_at": "2026-07-31T06:25:45.000000Z" }, { "uid": "w4beoawsjlzh", "public_id": "cal_w4beoawsjlzh", "short_link": null, "name": "magnam perspiciatis nesciunt", "internal_name": null, "description": "

Est quam commodi excepturi possimus. Expedita totam vel perferendis nesciunt est accusamus. Fugiat recusandae ipsam ducimus repudiandae. Possimus qui et tempore quasi architecto repellat.

", "timezone": "UTC", "week_begins": 4, "public_url": "https://addcal.co/c/w4beoawsjlzh", "upcoming_events_count": 2, "events_count": 4, "created_at": "2026-07-31T06:25:45.000000Z", "updated_at": "2026-07-31T06:25:45.000000Z" }, { "uid": "z9s82mzzyz9h", "public_id": "cal_z9s82mzzyz9h", "short_link": null, "name": "ut culpa doloribus", "internal_name": null, "description": "

Esse in voluptatem error delectus. Nesciunt delectus qui perferendis praesentium nihil tenetur. Eum sequi aut voluptatibus.

", "timezone": "UTC", "week_begins": 2, "public_url": "https://addcal.co/c/z9s82mzzyz9h", "upcoming_events_count": 2, "events_count": 4, "created_at": "2026-07-31T06:25:45.000000Z", "updated_at": "2026-07-31T06:25:45.000000Z" }, { "uid": "zn7jthtmcu6v", "public_id": "cal_zn7jthtmcu6v", "short_link": null, "name": "blanditiis qui similique", "internal_name": null, "description": "", "timezone": "UTC", "week_begins": 3, "public_url": "https://addcal.co/c/zn7jthtmcu6v", "upcoming_events_count": 5, "events_count": 12, "created_at": "2026-07-31T06:25:45.000000Z", "updated_at": "2026-07-31T06:25:45.000000Z" }, { "uid": "53shwnly2hec", "public_id": "cal_53shwnly2hec", "short_link": null, "name": "mollitia est sunt", "internal_name": null, "description": "", "timezone": "UTC", "week_begins": 6, "public_url": "https://addcal.co/c/53shwnly2hec", "upcoming_events_count": 2, "events_count": 4, "created_at": "2026-07-31T06:30:17.000000Z", "updated_at": "2026-07-31T06:30:17.000000Z" }, { "uid": "dtm5tai0heff", "public_id": "cal_dtm5tai0heff", "short_link": null, "name": "sit delectus aliquam", "internal_name": "ea sed esse", "description": "", "timezone": "UTC", "week_begins": 3, "public_url": "https://addcal.co/c/dtm5tai0heff", "upcoming_events_count": 2, "events_count": 4, "created_at": "2026-07-31T06:30:17.000000Z", "updated_at": "2026-07-31T06:30:17.000000Z" }, { "uid": "8lkpjn1v9478", "public_id": "cal_8lkpjn1v9478", "short_link": null, "name": "eveniet a nulla", "internal_name": "velit provident aperiam", "description": "", "timezone": "UTC", "week_begins": 2, "public_url": "https://addcal.co/c/8lkpjn1v9478", "upcoming_events_count": 4, "events_count": 24, "created_at": "2026-07-31T06:30:17.000000Z", "updated_at": "2026-07-31T06:30:17.000000Z" } ] } ``` ### Create Calendar `POST /api/calendars` **Body parameters** (`application/json`) - `name` (string, required): Must not be greater than 255 characters. - `internal_name` (string, optional): Must not be greater than 255 characters. - `description` (string, optional): Must not be greater than 255 characters. - `timezone` (string, required): Must be a valid time zone, such as Africa/Accra. - `week_begins` (integer, required): No description. Options: `1`, `2`, `3`, `4`, `5`, `6`, `0`. **Example request** ```bash curl --request POST \ --url 'https://addcal.co/api/calendars' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "name": "jdwajjqulnuo", "internal_name": "fozocwhwmzs", "description": "Quia ullam dolor aperiam esse tenetur.", "timezone": "Asia/Kuwait", "week_begins": 2 }' ``` ### Get Calendar `GET /api/calendars/{public_id}` **Path parameters** - `public_id` (string, required): The ID of the public. **Example request** ```bash curl --request GET \ --url 'https://addcal.co/api/calendars/{public_id}' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Accept: application/json' ``` **Response 200** ```json { "data": { "uid": "p9v02qsz079d", "public_id": "cal_p9v02qsz079d", "short_link": null, "name": "Test RSVP Cal", "internal_name": null, "description": "", "timezone": "Australia/Adelaide", "week_begins": 4, "public_url": "https://addcal.co/c/p9v02qsz079d", "upcoming_events_count": 3, "events_count": 71, "created_at": "2025-07-27T06:43:09.000000Z", "updated_at": "2025-11-18T03:43:23.000000Z" } } ``` ### Update Calendar `PUT /api/calendars/{public_id}` **Path parameters** - `public_id` (string, required): The ID of the public. **Body parameters** (`application/json`) - `name` (string, required): Must not be greater than 255 characters. - `internal_name` (string, optional): Must not be greater than 255 characters. - `description` (string, optional): Must not be greater than 255 characters. - `timezone` (string, required): Must be a valid time zone, such as Africa/Accra. - `week_begins` (integer, required): No description. Options: `1`, `2`, `3`, `4`, `5`, `6`, `0`. **Example request** ```bash curl --request PUT \ --url 'https://addcal.co/api/calendars/{public_id}' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "name": "btrdgrjnarzvbyqc", "internal_name": "kmdeylc", "description": "Voluptatem nihil et ut id.", "timezone": "America/Yakutat", "week_begins": 4 }' ``` ### Delete Calendar `DELETE /api/calendars/{public_id}` **Path parameters** - `public_id` (string, required): The ID of the public. **Example request** ```bash curl --request DELETE \ --url 'https://addcal.co/api/calendars/{public_id}' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Accept: application/json' ``` ### Generate Signed URL `POST /api/calendars/{calendar_public_id}/signed-url` Generate a signed URL for a protected calendar. The URL includes an expiry timestamp and a cryptographic signature, and expires after the specified number of days. The calendar must have an access code set. If no `expiry_days` is provided, the calendar's configured `signed_url_expiry_days` is used, or 30 days as a default. The returned URL grants temporary access based on its signature validity, without exposing the access code. It can be shared with users who need time-limited access. **Path parameters** - `calendar_public_id` (string, required): The ID of the calendar public. **Body parameters** (`application/json`) - `expiry_days` (integer, optional): Number of days until the signed URL expires. Min 1, max 365. **Example request** ```bash curl --request POST \ --url 'https://addcal.co/api/calendars/{calendar_public_id}/signed-url' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "expiry_days": 30 }' ``` **Response 200** ```json { "url": "https://addcal.co/c/cal_abc123?expires=1741000000&signature=abc..." } ``` **Response 422** ```json { "error": "Calendar does not have an access code set." } ```