Calendar API
Calendar in the Broker & Agent API: everything on the calendar in a window; book time
Base URL: https://workspace.brokerandagent.com/api/public/v1. Every call needs an API key or OAuth token.
- Everything on the calendar in a window:
GET /calendar/events - 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
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. |
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 } |
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
Scope: crm.write · Role:
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. |
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 } |
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). |
Something missing or wrong? Email support@brokerandagent.com and