> ## Documentation Index > Fetch the complete documentation index at: https://docs.maxcare.ai/llms.txt > Use this file to discover all available pages before exploring further. # List calendar events > Non-bookable time on a provider's or facility's calendar, with absolute start/end instants. `supported: false` means this organization's EHR does not expose a standalone event list — its availability search already subtracts blocking time. ## OpenAPI ````yaml /openapi-v3.json get /schedule/calendar-events openapi: 3.0.0 info: title: Max AI Public API description: API for third-party marketplace apps version: '3.0' contact: {} servers: - url: https://api.maxcare.ai/v3 security: [] tags: [] paths: /schedule/calendar-events: get: tags: - Schedule summary: List calendar events description: >- Non-bookable time on a provider's or facility's calendar, with absolute start/end instants. `supported: false` means this organization's EHR does not expose a standalone event list — its availability search already subtracts blocking time. operationId: SchedulePublicController_listCalendarEvents parameters: - name: facilityId required: false in: query description: Facility ID (fac_…) schema: type: string - name: providerId required: false in: query description: Provider ID (prv_…) schema: type: string - name: from required: true in: query description: Window start (YYYY-MM-DD, inclusive) schema: example: '2026-08-01' type: string - name: to required: true in: query description: Window end (YYYY-MM-DD, inclusive) schema: example: '2026-09-30' type: string - name: blockingOnly required: false in: query description: Only return events that consume availability schema: type: boolean example: true - name: X-Organization-Id in: header required: true schema: type: string description: Target clinic organization ID responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListCalendarEventsSuccessResponse' '400': description: Missing or invalid request parameter content: application/json: schema: $ref: '#/components/schemas/PublicApiBadRequestResponse' '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/PublicApiUnauthorizedResponse' '403': description: Insufficient scope content: application/json: schema: $ref: '#/components/schemas/PublicApiForbiddenResponse' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/PublicApiRateLimitResponse' '502': description: EHR sync failed content: application/json: schema: $ref: '#/components/schemas/PublicApiBadGatewayResponse' '503': description: EHR integration unavailable content: application/json: schema: $ref: '#/components/schemas/PublicApiServiceUnavailableResponse' security: - api-key: [] components: schemas: ListCalendarEventsSuccessResponse: type: object properties: code: type: string description: Response code example: success data: $ref: '#/components/schemas/ListCalendarEventsData' required: - code - data PublicApiBadRequestResponse: type: object properties: code: type: string description: Error code example: bad_request message: type: string description: Human-readable error message example: '''id'' must be a valid UUID' trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiUnauthorizedResponse: type: object properties: code: type: string description: Error code example: unauthorized message: type: string description: Human-readable error message example: Invalid or missing API key trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiForbiddenResponse: type: object properties: code: type: string description: Error code example: forbidden message: type: string description: Human-readable error message example: Insufficient scope trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiRateLimitResponse: type: object properties: code: type: string description: Error code example: rate_limit_exceeded message: type: string description: Human-readable error message example: Rate limit exceeded. Maximum 1000 requests per 60 seconds. trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiBadGatewayResponse: type: object properties: code: type: string description: Error code example: unexpected_integration_error message: type: string description: Human-readable error message example: EHR sync failed trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiServiceUnavailableResponse: type: object properties: code: type: string description: Error code example: server_unresponsive message: type: string description: Human-readable error message example: EHR integration is not available for this note trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id ListCalendarEventsData: type: object properties: calendarEvents: type: array items: $ref: '#/components/schemas/CalendarEventResponse' meta: $ref: '#/components/schemas/FreshnessMetaResponse' supported: type: boolean description: Whether this organization's EHR exposes a standalone event list example: true required: - calendarEvents - meta - supported CalendarEventResponse: type: object properties: externalId: type: string description: >- The EHR's own event identifier (vendor-opaque, NOT a Max AI prefixed ID — calendar events are not addressable resources) example: 88213:2026-08-03 providerIds: example: - prv_35103413aaaa4bbbccccddddeeeeffff type: array items: type: string facilityIds: example: - fac_2706aaaa4bbbccccddddeeeeffff1111 type: array items: type: string startsAt: type: string example: '2026-08-03T12:00:00-04:00' endsAt: type: string example: '2026-08-03T13:00:00-04:00' blocking: type: boolean description: Whether the event consumes availability example: true notes: type: string nullable: true example: null description: Calendar free text is omitted from schedule responses. visible: type: boolean example: true required: - externalId - providerIds - facilityIds - startsAt - endsAt - blocking - notes - visible FreshnessMetaResponse: type: object properties: sourceSyncedAt: type: string description: >- When the underlying data was last synced from, or read from, the EHR. Null means complete sync coverage for the requested scope and dates is unknown. Read `sourceKind` before treating this as a lag measurement — on a live read it is the moment of the read itself, so `now - sourceSyncedAt` is always ~0 and measures nothing. nullable: true example: '2026-07-26T12:59:31.000Z' sourceKind: type: string enum: - live_read - mirror description: >- What `sourceSyncedAt` actually is. `live_read`: the endpoint went to the EHR for this request, so the timestamp is the read time and there is no lag to measure. `mirror`: the timestamp is a real sync watermark and `now - sourceSyncedAt` IS the lag. Slot searches use `mirror` unless strong consistency is requested. A consumer computing mirror lag must skip `live_read` responses rather than average a structural zero into its numbers. example: live_read maxStalenessSeconds: type: number description: The staleness this endpoint is designed to stay within, in seconds example: 60 strongConsistency: type: boolean description: >- Whether the response bypassed caches and read the EHR live (`?consistency=strong`) example: false required: - sourceSyncedAt - sourceKind - maxStalenessSeconds - strongConsistency securitySchemes: api-key: scheme: bearer bearerFormat: JWT type: http description: Marketplace API key ````