# Calendar API

> Calendar in the Broker & Agent API: everything on the calendar in a window; book time on the calendar.

Base URL: `https://workspace.brokerandagent.com/api/public/v1`. Every call needs an [API key or OAuth token](https://brokerandagent.com/developers/api/authentication).

- [Everything on the calendar in a window](#everything-on-the-calendar-in-a-window): `GET /calendar/events`
- [Book time on the calendar](#book-time-on-the-calendar): `POST /calendar/events`

## Everything on the calendar in a window

`GET /calendar/events`

Appointments with their repeats expanded, tasks at their due times, and deal closings and milestones as all-day events: what the private calendar link publishes. Calendars the person subscribed to (Google, iCal feeds) stay in the app. A `from` or `to` date alone is that whole day on the person's clock, and a time without a zone is on that clock too.

Scope: `crm.read`

**Parameters**

| Name | In | Type | |
|---|---|---|---|
| `from` | query | date-time or null | Window start; defaults to the start of today on the person's clock. Cut to 64 characters. |
| `to` | query | date-time or null | Window end; defaults to 14 days after the start. At most 120 days after it. Cut to 64 characters. |

```bash
curl https://workspace.brokerandagent.com/api/public/v1/calendar/events \
  -H "Authorization: Bearer bak_YOUR_KEY"
```

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | The window it read, the person's zone, and the events in start order. | { `from`: date-time, `to`: date-time, `timezone`: string, `events`: array of [CalendarEvent](https://brokerandagent.com/developers/api/reference/objects#calendarevent) } |
| `401` | No credential, or one that's unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). |  |
| `403` | The credential lacks the scope (insufficient_scope, naming it in `scope`), the record isn't the person's to change (forbidden), the connection wasn't granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant's tools (wrong_audience). |  |
| `422` | A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused). |  |
| `429` | Too many requests for this credential; wait for Retry-After (rate_limited). |  |

## Book time on the calendar

`POST /calendar/events`

An appointment as the app's dialog books it: with a client or as a personal block, repeating, with teammates on it (seat ids from GET /seats), and a kind that may be one of the workspace's own appointment types. Teammates need the collaboration add-on; without it they're left off and the booking stands.

Scope: `crm.write` · Role: agent or above

**Body**

| Field | Type | |
|---|---|---|
| `title` (required) | string | Cut to 300 characters. |
| `startAt` (required) | string |  |
| `endAt` | date-time | An unknown value is ignored, not refused. |
| `contactId` | string or null | Cut to 64 characters. |
| `kind` | string or null | Cut to 40 characters. |
| `location` | string or null | Cut to 300 characters. |
| `notes` | string or null | Cut to 10000 characters. |
| `recurrence` | `daily`, `weekly`, `biweekly`, `monthly` | An unknown value is ignored, not refused. |
| `attendees` | array of string | Up to 50 items. An unknown value is ignored, not refused. |

```bash
curl -X POST https://workspace.brokerandagent.com/api/public/v1/calendar/events \
  -H "Authorization: Bearer bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Call Dana back","startAt":"2026-10-02T15:00:00Z"}'
```

**Responses**

| Status | | Returns |
|---|---|---|
| `201` | The appointment. | { `appointment`: [AppointmentDetail](https://brokerandagent.com/developers/api/reference/objects#appointmentdetail) } |
| `400` | The body isn't a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key). |  |
| `401` | No credential, or one that's unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). |  |
| `403` | The credential lacks the scope (insufficient_scope, naming it in `scope`), the record isn't the person's to change (forbidden), the connection wasn't granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant's tools (wrong_audience). |  |
| `404` | No such record, or one the credential's person can't see (not_found). |  |
| `409` | A request with this Idempotency-Key is still being handled (idempotency_in_progress, with Retry-After), or the call conflicts with the record's state (flow_off, in_progress). |  |
| `422` | A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused). |  |
| `429` | Too many requests for this credential; wait for Retry-After (rate_limited). |  |

---

Source: https://brokerandagent.com/developers/api/reference/calendar
