Calendar and availability

API v1 separates four scheduling concepts:

Resource	Contract
Appointments	Bounded list, get, create, compare-and-set update, archive, and restore
Absences	Bounded list, get, create, compare-and-set update, archive, and restore
Availability	Read-only intervals derived for an explicit time zone and bounded window
Planned work	Task schedules with atomic, asynchronous whole-schedule replacement

Appointment and absence list requests require start and end. Availability additionally requires an IANA timeZone. These bounds are part of the safety contract; do not use the calendar resources as an unbounded history export.

Acting user and delegated access

The base appointment and absence scopes cover the credential’s normal acting-user boundary. Reading another user’s appointments requires appointments:delegated:read; writing them requires appointments:delegated:write. Foreign absence reads require absences:delegated:read, while administrative absence writes require absences:admin:write. Foreign availability requires availability:delegated:read.

An overlay scope is necessary but not sufficient. TeamGrid also checks active membership, the relevant product permission and, for appointments or availability, calendar sharing. A caller cannot gain delegated access by supplying another userId without those checks.

Concurrency and lifecycle

Create requests support Idempotency-Key. Read the latest appointment or absence before changing it, then send its strong revision with If-Match. A missing precondition returns 428; a stale revision returns 412. Archive and restore are explicit lifecycle operations rather than generic field patches.

Planned-work replacement has a separate asynchronous operation resource because it replaces the complete task schedule. Follow the planned-work guide for its revision, idempotency, and polling contract.

Calendar, absence, availability, and planned-work data are intentionally unavailable through MCP, including the all profile.