Calendar API

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

Generated from the product on Nov 17, 2026

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

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.
Shell
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 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.
Shell
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 we’ll fix it.