Calendar tools

For: developers connecting an HTTP or MCP client. What you need: a connection delegated to an active staff member with Calendar permission and the required grants.

Calendar tools use the same permissions and actions as the browser. Read the Calendar manual for event timing, source dates and exchange behavior. The tool reference lists all 29 Calendar tools and routes.

Use calendar:read for reads and previews, calendar:prepare for ordinary saved changes, and calendar:execute for approval and sensitive execution. Both generic view tools use calendar:read. The person needs calendar.use; owned shared-calendar writes also require calendar.manage.

Personal calendars stay private to their owner. Shared readers cannot edit events. Guests cannot use Calendar. Current source-record access applies to every linked event and projected date.

Read a period

Call calendar_read, or GET /api/v1/calendar.

Read the returned data projection and its more flag. more: true means the bounded view is incomplete. Narrow the selection before exporting or claiming completeness.

calendar_calendars lists up to 100 accessible calendars. calendar_calendar_get returns one calendar and its current version. calendar_event_get returns one event and its current event and calendar versions.

calendar_lookups finds permitted users, teams, contacts or leads. Pass kind, optional search of up to 100 characters and up to 100 selected IDs. Results contain up to 150 choices.

Generic views_work_calendar and views_calendar_event use the record-view format. Their current record access still applies.

Preview and save an event

1. Read the destination with calendar_calendar_get.
2. Call calendar_event_prepare with its calendar_id, calendar_version, title and timing.
3. Show the normalized proposal to the person.
4. Call calendar_event_create with those values and an idempotency key.
5. Keep the returned event version and calendar_version for later changes.

Preparation validates and normalizes the event. It saves nothing, reserves no identifier and sends no mail.

Supported parents are customer, lead, deal, project (engagement), task, financial document (document), purchase, board, board list, card, Doc and booking. Derived records such as files and comments cannot be parents. Linking grants no access.

Keep timing exact

Pass starts_local and ends_local as YYYY-MM-DDTHH:mm for a timed event. For all-day events, use YYYY-MM-DD dates. Always include timezone and boolean all_day.

Use recurrence: null for a single event. A recurrence has frequency (daily, weekly, monthly or yearly) and integer interval from 1 to 366. Weekly rules can include weekdays, using 1 for Monday through 7 for Sunday. An optional count from 1 to 5,000 or inclusive until date ends the rule; use only one.

An all-day end is exclusive. Timed repetitions retain their event-zone wall clock, month-end and leap-day rules. A daylight-saving gap advances the occurrence; a repeated time uses the earlier instant. See the worked rules.

Returned exceptions is an array. Each row names its original recurrence_id and its cancellation or replacement fields. Do not turn that array into an object keyed by dates. Omit it from ordinary create or update input; use calendar_event_exception for a change to one occurrence.

Change or cancel

calendar_event_update needs the event id, current version, calendar_version and changed fields inside input. calendar_event_cancel needs the same identities and versions. Both need an idempotency key.

Use calendar_event_exception for one original occurrence. Include its recurrence_id and an input containing cancelled, title or replacement timing. Replacement timing keeps the series zone and all-day policy, with recurrence: null. A moved occurrence keeps its original identity.

Calendar updates and archiving need their current version. Calendar creation accepts name, optional visibility (personal or shared) and readers with users and teams arrays. A personal calendar cannot keep reader grants.

Every ordinary write needs an idempotency key. Keep the same key and payload when a response is uncertain. Re-read after a version conflict and review the changed proposal before using a new key. A replay still checks current authority.

Import and export

calendar_import accepts calendar_id, calendar_version, ics and an idempotency key. Send the ICS text, up to 2,097,152 bytes and 500 event series. Parsing and saving are atomic. An unchanged UID reimport creates no duplicate; changed content updates that imported event in the same calendar.

Imported addresses remain data only. Import never sends mail, accepts an invitation or loads remote content.

For export, call calendar_export_prepare with the selected query. Show the returned review_url to the person. After approval, call calendar_export with the approval id, nonce and an idempotency key.

The result provides an expiring, single-use download_url and MCP resource_uri. They are temporary capabilities. Do not keep them in logs or history. Download still checks current access. An approved replay can provide a fresh link.

A selected repeating event exports its complete series. Repetitions can extend beyond the chosen period. A truncated view refuses export.

Create and revoke a feed

Call calendar_feed_create_prepare with filters. The person reviews ongoing disclosure and the named selection. After approval, execute calendar_feed_create with the approval id, nonce and an idempotency key.

The result's url appears once and is temporary output. Do not persist it in client history, logs or approval receipts. A lost-response replay returns url: null. Revoke the returned subscription id, then prepare a replacement.

calendar_subscriptions returns owned active feed metadata without its secret or address. If any selected calendar or project becomes unreadable, filters is null. The original selection stays in force. The owned subscription id still permits revocation. Null hides selection details and differs from empty filter arrays, which mean All. Feed creation still requires a non-null filters object.

Each person can keep up to 100 active feeds. Feed filters can include timezone; omitted values use the company time zone.

calendar_subscription_revoke permanently revokes one owned subscription. It needs its id and an idempotency key. A future grant or account reactivation does not restore a revoked feed.

Feeds select from 31 days before today until 335 days after today, excluding that final date in the saved zone. Current actor and record access apply on every fetch. Selected repeating events retain their complete series. See feed access and offboarding.

Review invitations and delivery

1. Call calendar_invitation_review with the event ID and current event and calendar versions.
2. Read the frozen review with calendar_invitation_get.
3. Call calendar_invite_prepare with that preparation's ID.
4. Show the returned approval review_url to the person.
5. After approval, execute calendar_invite with the approval id, nonce and an idempotency key.
6. Call calendar_invitation_status with the invitation preparation's ID to check actual delivery results.

The invitation review lasts 15 minutes. Event content, recipients, sender, versions and permissions must still match. Client-supplied addresses cannot replace approved recipient identities.

pending means no invitation was queued. queued and uncertain do not confirm transport acceptance. delivered means the mail transport accepted the invitation; it does not prove inbox receipt.

A failed or uncertain delivery can expose a delivery-record ID in the result. To retry, call calendar_mail_retry_prepare with that ID. The person must approve the exact recipient, content, lifetime attempt count and duplicate warning. Execute calendar_mail_retry with the new approval's ID and nonce. Never retry an uncertain invitation automatically.

The original attempt may already have reached its recipient. A retry can send a duplicate. A new review is required after a change or lost authority; an approval cannot restore access.

For errors and approval expiry, use Errors, retries and revocation and Approve sensitive steps.

The read result includes the company’s week_start (monday or sunday). Week ranges use that choice. Agenda covers seven days.