# 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)

## Create Event

A simplified endpoint for creating events with smart defaults and automatic calendar management.

This endpoint provides a streamlined way to create events by handling calendar creation and management automatically. It offers three ways to specify a calendar:
1. Use an existing calendar by providing its `calendar_uid`
2. Create or reuse a calendar by name using `calendar_name`
3. Use a default calendar (automatically created if needed)

Key features:
- Automatic 1-hour duration if no end time is specified
- Flexible team selection with smart defaults
- Automatic calendar creation with sensible defaults
- Timezone inheritance from calendar if not specified
- Support for all-day events

The response includes the created event details along with calendar information and add-to-calendar links for various platforms.

### /api/events

`POST /api/events`

**Query parameters**

- `with_html` (boolean, optional): Include HTML variants for calendar links in the response

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

- `title` (string, required): The title of the event. Must not be greater than 255 characters.
- `description` (string, optional): A detailed description of the event.
- `location` (string, optional): The location where the event will take place. Must not be greater than 255 characters.
- `is_all_day` (boolean, optional): Whether this is an all-day event.
- `is_virtual` (boolean, optional): Whether this is a virtual/online event.
- `organiser_name` (string, optional): The name of the event organiser. Must not be greater than 255 characters.
- `organiser_email` (string, optional): The email address of the event organiser. Must be a valid email address. Must not be greater than 191 characters.
- `recurrence_rule` (string, optional): iCalendar RRULE string for recurring events (e.g. FREQ=DAILY;INTERVAL=1;COUNT=3).
- `series_title` (string, optional): Title for the recurring event series. Defaults to the event title if not provided. Must not be greater than 255 characters.
- `has_rsvp` (boolean, optional): Whether this event allows RSVP responses.
- `date_start` (string, required): The start date and time of the event. Must be a valid date.
- `date_end` (string, required): The end date and time of the event. If not provided, defaults to 1 hour after start time. Must be a valid date. Must be a date after or equal to date_start.
- `timezone` (string, optional): The timezone for the event. Defaults to calendar timezone if not provided. Must be a valid time zone, such as Africa/Accra.
- `busy_type` (string, optional): Whether the event shows as busy or free on calendars. Options: busy, or free, calendar default when null. Options: `busy`, `free`.
- `reminder_before` (integer, optional): Minutes before the event to send a notification. Common values: 0, 5, 10, 15, 30, 60, 120, 1440 (1 day), etc. Must be at least 0.
- `short_link` (string, optional): Custom short link for the event. Only available for subscribers. Must match the regex /^[a-zA-Z0-9-]+$/. Must not be greater than 50 characters.
- `team_uid` (string, optional): The unique identifier of the team to create the event for. Defaults to current team or first available team.
- `calendar_uid` (string, optional): The unique identifier of an existing calendar to create the event in.
- `calendar_name` (string, optional): Name of the calendar to create or use. Cannot be used with calendar_uid. Must not be greater than 255 characters.

**Example request**

```bash
curl --request POST \
  --url 'https://addcal.co/api/events' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Team Meeting",
    "description": "Monthly team sync to discuss project progress and upcoming milestones.",
    "location": "Conference Room A or https://zoom.us/j/123456789",
    "is_all_day": false,
    "is_virtual": false,
    "organiser_name": "Jane Smith",
    "organiser_email": "jane@example.com",
    "recurrence_rule": "FREQ=WEEKLY;BYDAY=MO;COUNT=10",
    "series_title": "Weekly Team Meeting",
    "has_rsvp": false,
    "date_start": "2024-03-25 14:00:00",
    "date_end": "2024-03-25 15:00:00",
    "timezone": "America/New_York",
    "busy_type": "busy",
    "reminder_before": 30,
    "short_link": "my-event",
    "team_uid": "team_abc123",
    "calendar_uid": "cal_xyz789",
    "calendar_name": "Team Meetings"
}'
```

**Response 200**

```json
{
    "data": {
        "uid": "gazgxmfthgxz",
        "public_id": "evt_gazgxmfthgxz",
        "calendar_uid": "cal_w4tpbs2tx7nu",
        "short_link": null,
        "title": "Quia libero tempora ea dolorem adipisci nemo ut.",
        "internal_name": null,
        "is_draft": false,
        "description": "<p>Rem odio consequatur et qui consequatur et veritatis. Saepe perferendis eos minima.</p>\n\n<p>Necessitatibus culpa distinctio sint veniam. Qui numquam consequatur eum nam ut et. Vero corrupti fugit ut voluptatem repudiandae omnis. Voluptate eaque nihil repellendus maiores autem dolores.</p>",
        "location": "38974 Ryan Fields Suite 946\nNew Lelahburgh, WI 65655-2316",
        "is_all_day": false,
        "has_rsvp": false,
        "has_calendar_invites": false,
        "rsvp_limit": null,
        "is_recurring": false,
        "recurrence_rule": null,
        "recurrence_text": null,
        "date_start": "2026-08-12T11:12:34+11:00",
        "date_end": "2026-08-12T14:12:34+11:00",
        "timezone": "Pacific/Noumea",
        "busy_type": null,
        "reminder_before": null,
        "date_range_formatted": "Wed, Aug 12, 2026 11:12 AM - 2:12 PM",
        "public_url": "http://addcal.co/e/gazgxmfthgxz",
        "embed_url": "http://addcal.co/e/gazgxmfthgxz",
        "location_url": null,
        "image_url": null,
        "timezone_readable": "+11 / GMT+11:00",
        "calendar": {
            "uid": "w4tpbs2tx7nu",
            "public_id": "cal_w4tpbs2tx7nu",
            "short_link": null,
            "name": "aliquid ea nihil",
            "internal_name": "quibusdam qui et",
            "description": "<p>Praesentium corrupti rerum ad libero nam sapiente. Soluta voluptatem voluptas dolorum veritatis iure aliquid similique. Eum ad repellendus delectus magnam.</p>",
            "timezone": "Asia/Krasnoyarsk",
            "week_begins": 4,
            "public_url": "http://addcal.co/c/w4tpbs2tx7nu",
            "created_at": "2026-08-08T06:22:37.000000Z",
            "updated_at": "2026-08-08T06:22:37.000000Z"
        },
        "created_at": "2026-08-08T06:22:37.000000Z",
        "updated_at": "2026-08-08T06:22:37.000000Z"
    },
    "links": {
        "event_page": "http://addcal.co/e/gazgxmfthgxz",
        "auto": "https://addcal.co/e/gazgxmfthgxz/auto",
        "google": "https://addcal.co/e/gazgxmfthgxz/google",
        "apple": "https://addcal.co/e/gazgxmfthgxz/apple",
        "outlook": "https://addcal.co/e/gazgxmfthgxz/outlook",
        "outlook_web": "https://addcal.co/e/gazgxmfthgxz/outlook_web",
        "yahoo": "https://addcal.co/e/gazgxmfthgxz/yahoo",
        "office365": "https://addcal.co/e/gazgxmfthgxz/office365",
        "ics": "https://addcal.co/e/gazgxmfthgxz/ics"
    },
    "html": {
        "single-button": "Add to Calendar Button",
        "icon-buttons-single-row": "Buttons With Icons",
        "icons": "Text with Icons",
        "dot-sep": "Text (dot separated)",
        "space-sep": "Text (space separated)"
    }
}
```

**Response 409** — When the team's event limit has been exceeded

```json
{
    "message": "You have reached your monthly event limit of 10. Please upgrade your plan to create more events.",
    "current": 10,
    "limit": 10,
    "remaining": 0,
    "would_exceed_by": 1,
    "is_unlimited": false,
    "limit_type": "monthly"
}
```