---
name: unified-calendar
description: >-
  Build scheduling and calendar features against many calendar providers (Google
  Calendar, Microsoft Outlook, Zoom, and more) through the single Unified.to
  Calendar API. Use when a coding task involves reading or creating calendars and
  events, checking availability / busy times, or generating scheduling links and
  webinars across one or more providers.
license: MIT
metadata:
  category: calendar
  api_base: https://api.unified.to
  docs: https://docs.unified.to/calendar/overview
---

# Build a scheduling / calendar app with the Unified.to Calendar API

Unified.to normalizes many calendar providers behind one REST API. Write your
scheduling integration once and it works across every supported provider. This
skill teaches an agent how to build against the Unified Calendar API.

## When to use this skill

Use this skill when the task is to:

- Read and create calendar events / meetings
- Check a user's availability (busy times) before booking
- Generate scheduling links
- Manage webinars and access recordings

## Prerequisites

1. A Unified.to workspace with an **API key** and **Workspace ID**.
2. An activated calendar integration (e.g. Google Calendar) — start in the
   Sandbox.
3. A **connection ID** from the embedded Authorization component
   (https://docs.unified.to/concepts/embedded-components).

Keep the API key server-side only.

## Core request pattern

```
https://api.unified.to/calendar/{connection_id}/{object}
```

Authenticate every request:

```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Regional base URLs: `api.unified.to` (NA), `api-eu.unified.to` (EU),
`api-au.unified.to` (AU).

## Data objects

| Object      | Purpose                                       |
| ----------- | --------------------------------------------- |
| `calendar`  | A calendar                                    |
| `event`     | An event / meeting                            |
| `busy`      | Busy time blocks for availability (read-only) |
| `link`      | A scheduling link                             |
| `webinar`   | A webinar                                     |
| `recording` | A meeting/webinar recording (read-only)       |

### Supported operations (event shown; calendar / link / webinar follow the same shape)

| Method   | Path                             | Description        |
| -------- | -------------------------------- | ------------------ |
| `GET`    | `/calendar/{cid}/event`          | List events        |
| `GET`    | `/calendar/{cid}/event/{id}`     | Get one event      |
| `POST`   | `/calendar/{cid}/event`          | Create an event    |
| `PATCH`  | `/calendar/{cid}/event/{id}`     | Update an event    |
| `DELETE` | `/calendar/{cid}/event/{id}`     | Delete an event    |
| `GET`    | `/calendar/{cid}/busy`           | Get busy times     |

The same verbs apply to `calendar`, `link`, and `webinar`. `busy` and
`recording` are read-only.

Not every provider supports every object or field. Check the **Feature Support**
tab in `app.unified.to`; a `501` response means unsupported.

## Pagination & filtering

- `limit` (max 100) and `offset` (zero-based).
- Filter events by time window with `start_gte` and `end_le`
  (`YYYY-MM-DDTHH:MM:SSZ`), and use `updated_gte` for incremental sync.

## Example: check availability, then book (fetch)

```javascript
const BASE = 'https://api.unified.to';
const headers = {
    Authorization: `Bearer ${process.env.UNIFIED_API_KEY}`,
    'Content-Type': 'application/json',
};

// Check busy times for a window
const busy = await (
    await fetch(
        `${BASE}/calendar/${connectionId}/busy?start_gte=2025-06-01T09:00:00Z&end_le=2025-06-01T17:00:00Z`,
        { headers }
    )
).json();

// If the slot is free, create the event
await fetch(`${BASE}/calendar/${connectionId}/event`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
        title: 'Intro call',
        start_at: '2025-06-01T15:00:00Z',
        end_at: '2025-06-01T15:30:00Z',
        attendees: [{ emails: [{ email: 'guest@example.com' }] }],
    }),
});
```

Consult the event data model at https://docs.unified.to/calendar/event/model
for canonical fields.

## Example: with the official SDK

```bash
npm install @unified-api/typescript-sdk
```

```typescript
import { UnifiedTo } from '@unified-api/typescript-sdk';

const unified = new UnifiedTo({ security: { jwt: process.env.UNIFIED_API_KEY! } });

const { calendarEvents } = await unified.calendar.listCalendarEvents({
    connectionId,
    limit: 100,
});
```

SDKs for Python, PHP, Java, Go, C#, and Ruby: https://docs.unified.to/reference/sdks.

## Keeping data in sync (recommended)

- Register **webhooks** for `event` create/update/delete so bookings stay
  current without polling. See https://docs.unified.to/reference/webhooks and
  https://docs.unified.to/concepts/virtual_webhooks.

## Error handling

| Code | Meaning & action                                            |
| ---- | ----------------------------------------------------------- |
| 401  | Connection broken — re-authorize the end-user.              |
| 403  | Missing scopes — fix provider app + Unified.to scopes.      |
| 429  | Provider rate limit — back off; prefer webhook sync.        |
| 501  | Operation unsupported by provider — check Feature Support.  |

## References

- Calendar API overview & data model: https://docs.unified.to/calendar/overview
- Event data model: https://docs.unified.to/calendar/event/model
- REST basics: https://docs.unified.to/reference/rest
- Pagination & filtering: https://docs.unified.to/reference/pagination