Calendars

APIs for managing calendars

List Calendars#

GET/api/calendarsRequires authentication

Responses

200application/json
Show response attributes
dataarray of objects
Show child attributes
uidstring
public_idstring
short_linkstring · nullable
namestring
internal_namestring · nullable
descriptionstring
timezonestring
week_beginsinteger
public_urlstring
upcoming_events_countinteger
events_countinteger
created_atstring
updated_atstring
GET/api/calendars
curl --request GET \
  --url 'https://addcal.co/api/calendars' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json'
Response
{
    "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": 2,
            "events_count": 72,
            "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": "<p>Professional meetings, webinars, and business events.</p>",
            "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": "<p>Professional meetings, webinars, and business events.</p>",
            "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": "<p>Personal events, family gatherings, and appointments.</p>",
            "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": "<p>Professional meetings, webinars, and business events.</p>",
            "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": "<p>Seeded calendar for testing tag-filtered subscriptions.</p>",
            "timezone": "UTC",
            "week_begins": 1,
            "public_url": "https://addcal.co/c/vdp2pp652p6z",
            "upcoming_events_count": 0,
            "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": "<p>Same tags, but gated behind the subscriber info form.</p>",
            "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": "<p>Tags exist but allow_tag_selection is off - control case.</p>",
            "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": "<p>Repudiandae quos suscipit similique saepe maiores. Omnis officiis qui placeat voluptates. Quia sunt corporis quis quasi harum in odio.</p>",
            "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": "<p>Cum optio dolor ducimus vitae enim. Consequatur perferendis velit non cum. Accusamus aut quidem dicta et numquam.</p>",
            "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": "<p>Est quam commodi excepturi possimus. Expedita totam vel perferendis nesciunt est accusamus. Fugiat recusandae ipsam ducimus repudiandae. Possimus qui et tempore quasi architecto repellat.</p>",
            "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": "<p>Esse in voluptatem error delectus. Nesciunt delectus qui perferendis praesentium nihil tenetur. Eum sequi aut voluptatibus.</p>",
            "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": 2,
            "events_count": 24,
            "created_at": "2026-07-31T06:30:17.000000Z",
            "updated_at": "2026-07-31T06:30:17.000000Z"
        },
        {
            "uid": "ffyq1eyfpzn4",
            "public_id": "cal_ffyq1eyfpzn4",
            "short_link": null,
            "name": "Wedding",
            "internal_name": null,
            "description": "",
            "timezone": "Australia/Sydney",
            "week_begins": 1,
            "public_url": "https://addcal.co/c/ffyq1eyfpzn4",
            "upcoming_events_count": 1,
            "events_count": 1,
            "created_at": "2026-08-13T02:53:56.000000Z",
            "updated_at": "2026-08-13T02:53:56.000000Z"
        },
        {
            "uid": "4vym88ak6pnj",
            "public_id": "cal_4vym88ak6pnj",
            "short_link": null,
            "name": "Default Calendar",
            "internal_name": null,
            "description": "",
            "timezone": "Australia/Sydney",
            "week_begins": 1,
            "public_url": "https://addcal.co/c/4vym88ak6pnj",
            "upcoming_events_count": 0,
            "events_count": 4,
            "created_at": "2026-08-16T09:50:40.000000Z",
            "updated_at": "2026-08-16T09:50:40.000000Z"
        },
        {
            "uid": "77r9qzpie5xw",
            "public_id": "cal_77r9qzpie5xw",
            "short_link": null,
            "name": "Imported Events",
            "internal_name": null,
            "description": "<p>Events imported from your public event creations.</p>",
            "timezone": "Australia/Sydney",
            "week_begins": 1,
            "public_url": "https://addcal.co/c/77r9qzpie5xw",
            "upcoming_events_count": 0,
            "events_count": 1,
            "created_at": "2026-08-16T21:35:16.000000Z",
            "updated_at": "2026-08-16T21:35:16.000000Z"
        }
    ]
}

Create Calendar#

POST/api/calendarsRequires authentication

Body Parameters application/json

namestringrequired

Must not be greater than 255 characters.

internal_namestring · nullable

Must not be greater than 255 characters.

descriptionstring · nullable

Must not be greater than 255 characters.

timezonestringrequired

Must be a valid time zone, such as Africa/Accra.

week_beginsintegerrequired
Options: 1234560

Responses

409application/json
Show response attributes
messagestring
POST/api/calendars
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": "zxplduayr",
    "internal_name": "rjzj",
    "description": "Non repellendus eligendi impedit aspernatur.",
    "timezone": "Africa/Brazzaville",
    "week_begins": 5
}'
Response
{
    "message": "You have reached your calendar limit. Please upgrade your plan to create more calendars."
}

Get Calendar#

GET/api/calendars/{public_id}Requires authentication

Path Parameters

public_idstringrequired

The ID of the public.

Responses

200application/json
Show response attributes
dataobject
Show child attributes
uidstring
public_idstring
short_linkstring · nullable
namestring
internal_namestring · nullable
descriptionstring
timezonestring
week_beginsinteger
public_urlstring
upcoming_events_countinteger
events_countinteger
created_atstring
updated_atstring
GET/api/calendars/{public_id}
curl --request GET \
  --url 'https://addcal.co/api/calendars/{public_id}' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json'
Response
{
    "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": 2,
        "events_count": 72,
        "created_at": "2025-07-27T06:43:09.000000Z",
        "updated_at": "2025-11-18T03:43:23.000000Z"
    }
}

Update Calendar#

PUT/api/calendars/{public_id}Requires authentication

Path Parameters

public_idstringrequired

The ID of the public.

Body Parameters application/json

namestringrequired

Must not be greater than 255 characters.

internal_namestring · nullable

Must not be greater than 255 characters.

descriptionstring · nullable

Must not be greater than 255 characters.

timezonestringrequired

Must be a valid time zone, such as Africa/Accra.

week_beginsintegerrequired
Options: 1234560
PUT/api/calendars/{public_id}
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": "zsbvmmarvcxzpzneeqrugpwps",
    "internal_name": "xbaazfazbqwyhgqymyux",
    "description": "Voluptatem voluptatem ipsa sequi atque inventore.",
    "timezone": "America/Barbados",
    "week_begins": 5
}'

Delete Calendar#

DELETE/api/calendars/{public_id}Requires authentication

Path Parameters

public_idstringrequired

The ID of the public.

DEL/api/calendars/{public_id}
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-urlRequires authentication

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_idstringrequired

The ID of the calendar public.

Body Parameters application/json

expiry_daysinteger

Number of days until the signed URL expires. Min 1, max 365.

Responses

200application/json
Show response attributes
urlstringrequired

The generated signed URL with expiry and signature-based access

422application/json
Show response attributes
errorstring
POST/api/calendars/{calendar_public_id}/signed-url
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
{
    "url": "https://addcal.co/c/cal_abc123?expires=1741000000&signature=abc..."
}