# CalMonkey

> CalMonkey is one API for your users' Google Calendar, Microsoft 365, Outlook.com and Apple iCloud calendars: hosted connect pages, calendars, free/busy, events with guests, repeating events and meeting links, and signed webhooks. Field names and shapes follow Cronofy's calendar API.

The API is at https://api.calmonkey.com. People connect their calendars, and you manage your applications, at https://app.calmonkey.com. Every page of the documentation is also served as Markdown: add `.md` to its address.

## A working calendar in about five minutes

No calendar account has to be connected for a first run: an application calendar is hosted by CalMonkey and opened with your client credentials alone. In the commands, `$CLIENT_ID` and `$CLIENT_SECRET` are your application's, `$ACCESS_TOKEN` comes from step 2 and `$CALENDAR_ID` from step 3.

1. Sign in at https://app.calmonkey.com/sign-in with a Google or Microsoft account and create an application in the dashboard. It starts in test mode. Keep its client id and its client secret, which is shown once.
2. Open an application calendar with your client credentials. The answer has `access_token`, `refresh_token` and `sub`. The same `application_calendar_id` always opens the same calendar.

   ```sh
   curl -X POST "https://api.calmonkey.com/v1/application_calendars" \
     -H "Content-Type: application/json" \
     -d '{"client_id":"'"$CLIENT_ID"'","client_secret":"'"$CLIENT_SECRET"'","application_calendar_id":"test-calendar-1"}'
   ```
3. List the calendars and take the `calendar_id` of the one calendar it has.

   ```sh
   curl "https://api.calmonkey.com/v1/calendars" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
   ```
4. Write an event under your own `event_id`. The answer is `202` with an empty body, and the event can be read at once. Use dates close to today: reads cover 42 days back to 201 days ahead.

   ```sh
   curl -X POST "https://api.calmonkey.com/v1/calendars/$CALENDAR_ID/events" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"event_id":"booking-1042","summary":"Lash lift with Grace","description":"Booked through Your App","start":"2026-11-03T03:00:00Z","end":"2026-11-03T04:00:00Z","tzid":"Australia/Sydney","location":{"description":"12 Harbour St, Sydney"},"url":"https://yourapp.example/bookings/1042","transparency":"opaque"}'
   ```
5. Read free/busy. `include_managed=true` is needed here: events your own application wrote are left out without it.

   ```sh
   curl "https://api.calmonkey.com/v1/free_busy?tzid=Australia%2FSydney&from=2026-11-03&to=2026-11-04&include_managed=true" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
   ```

The same calls work on a person's Google, Microsoft or iCloud calendar once they have connected it: see the [quickstart](https://calmonkey.com/docs/quickstart.md).

## Docs

- [Overview](https://calmonkey.com/docs.md): What the API does, the hostnames, and how the pieces fit together.
- [Quickstart](https://calmonkey.com/docs/quickstart.md): Connect a calendar, exchange the code, list calendars, read free/busy, write an event and receive webhooks.
- [API reference](https://calmonkey.com/docs/api.md): Every endpoint with its parameters, request and response, including guests, repeating events and meeting links.
- [Errors and limits](https://calmonkey.com/docs/errors.md): Error shapes, rate limits, request ids and the webhook retry schedule.
- [Providers](https://calmonkey.com/docs/providers.md): Google, Microsoft 365, Outlook.com and Apple iCloud: what each needs, what each does with guests and meeting links, and how fresh the data is.
- [Migrating from Cronofy](https://calmonkey.com/docs/cronofy.md): Compatibility mode, what differs, and the steps to switch.

## API description

- [OpenAPI 3.1, JSON](https://calmonkey.com/openapi.json): Every endpoint with its parameters, request and response schemas and error shapes, generated from the schemas the API validates with.
- [OpenAPI 3.1, YAML](https://calmonkey.com/openapi.yaml): The same document as YAML.

## Optional

- [All of the documentation in one file](https://calmonkey.com/llms-full.txt): Every page above, one after the other, as Markdown.
- [Security](https://calmonkey.com/security): How credentials, tokens and event data are stored and deleted.
- [Privacy policy](https://calmonkey.com/privacy): What data is handled, and on whose behalf.