> ## Documentation Index > Fetch the complete documentation index at: https://docs.dialtu.com/llms.txt > Use this file to discover all available pages before exploring further. # Get bookable capacity per service > How many more appointments fit, per service, over a date range. ``capacity`` is summed PER PROVIDER, not unioned by instant: three providers free at 09:00 is three patients you can call, not one opening. It is net of booked appointments, buffers, breaks, blackouts and the notice/horizon policy, and it is an UPPER BOUND — booking one slot can eliminate more than one candidate once buffers interact. ``start_date`` defaults to today in the tenant's default timezone; every other date in the response is PROVIDER-local, which is the frame the whole calendar domain resolves in. ``days`` defaults to 7 to match the calendar agent tool's own ``search_days``. Querying a wider range than the agent that will do the calling is how a caller ends up queueing patients the agent will tell there is nothing available — see the integration guide. ## OpenAPI ````yaml GET /api/v2/public/calendar/availability openapi: 3.1.0 info: title: Dialtu Public API version: '2.0' description: >- Programmatic access to your Dialtu account: schedule AI voice calls, create contacts, push leads into Salesflow pipelines, book calendar appointments and read WhatsApp conversation history. Every request is authenticated with an API key created in the dashboard under **Settings → API Keys**, sent as `Authorization: Bearer pk_...`. servers: - url: https://api.dialtu.com description: Production - url: https://api.stg.dialtu.com description: Staging security: - ApiKeyBearer: [] tags: - name: Calls description: Schedule outbound AI voice calls. - name: Clients description: Create contacts in your account. - name: Salesflow description: Push leads into a pipeline through an API input node. - name: Salesflow pipelines description: Read a pipeline's stages and add, move or remove clients. - name: Calendar description: Check bookable capacity, book appointments and manage waiting lists. - name: WhatsApp description: Read-only conversation history and transcripts. paths: /api/v2/public/calendar/availability: get: tags: - Calendar summary: Get bookable capacity per service description: >- How many more appointments fit, per service, over a date range. ``capacity`` is summed PER PROVIDER, not unioned by instant: three providers free at 09:00 is three patients you can call, not one opening. It is net of booked appointments, buffers, breaks, blackouts and the notice/horizon policy, and it is an UPPER BOUND — booking one slot can eliminate more than one candidate once buffers interact. ``start_date`` defaults to today in the tenant's default timezone; every other date in the response is PROVIDER-local, which is the frame the whole calendar domain resolves in. ``days`` defaults to 7 to match the calendar agent tool's own ``search_days``. Querying a wider range than the agent that will do the calling is how a caller ends up queueing patients the agent will tell there is nothing available — see the integration guide. operationId: getCalendarAvailability parameters: - in: query name: start_date schema: anyOf: - type: string - type: 'null' description: >- First day of the range, `YYYY-MM-DD`. Defaults to today in the account's default timezone. title: Start Date required: false description: >- First day of the range, `YYYY-MM-DD`. Defaults to today in the account's default timezone. - in: query name: days schema: anyOf: - type: integer - type: 'null' description: >- Length of the range in days, 1–31. Defaults to 7, matching the calendar agent's own search window. title: Days required: false description: >- Length of the range in days, 1–31. Defaults to 7, matching the calendar agent's own search window. - in: query name: service_ids schema: anyOf: - type: string - type: 'null' description: >- Comma-separated service IDs to restrict the answer to. Omit for all services; an explicitly empty value is rejected. title: Service Ids required: false description: >- Comma-separated service IDs to restrict the answer to. Omit for all services; an explicitly empty value is rejected. - in: query name: professional_ids schema: anyOf: - type: string - type: 'null' description: Comma-separated professional IDs to restrict the answer to. title: Professional Ids required: false description: Comma-separated professional IDs to restrict the answer to. - in: query name: event_type_id schema: anyOf: - type: integer - type: 'null' description: Restrict capacity to one event type. title: Event Type Id required: false description: Restrict capacity to one event type. - in: query name: duration_minutes schema: anyOf: - type: integer - type: 'null' description: >- Appointment length to size slots by, overriding the service default. title: Duration Minutes required: false description: Appointment length to size slots by, overriding the service default. - in: query name: include schema: anyOf: - type: string - type: 'null' description: >- Comma-separated extras. `profiles` adds a per-professional breakdown under each service. title: Include required: false description: >- Comma-separated extras. `profiles` adds a per-professional breakdown under each service. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PublicCapacityResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/PublicCalendarErrorResponse' '401': description: Missing, malformed or revoked API key. content: application/json: schema: $ref: '#/components/schemas/DetailErrorResponse' examples: missing_header: summary: No Authorization header value: detail: Unauthorized invalid_key: summary: Unknown or revoked key value: detail: Invalid or expired API key. Please check your credentials. '422': description: The request did not match the documented schema. content: application/json: schema: $ref: '#/components/schemas/RequestValidationError' example: detail: - type: missing loc: - body - payload - phone_number msg: Field required '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/PublicCalendarErrorResponse' security: - ApiKeyBearer: [] components: schemas: PublicCapacityResponse: description: Response for GET /public/calendar/availability. properties: status: const: success default: success description: Always `success`. title: Status type: string data: $ref: '#/components/schemas/PublicCapacityDataSchema' description: Capacity data. required: - data title: PublicCapacityResponse type: object PublicCalendarErrorResponse: description: Error envelope shared by every public calendar endpoint. properties: status: const: error default: error description: Always `error`. title: Status type: string error_code: description: Machine-readable error code; branch on this, never on `message`. title: Error Code type: string message: description: Human-readable explanation. title: Message type: string details: anyOf: - {} - type: 'null' description: Extra context, e.g. `valid_service_names` or the offending `field`. title: Details required: - error_code - message title: PublicCalendarErrorResponse type: object DetailErrorResponse: description: 'Plain error body: `{"detail": "..."}`. No `error_code` is included.' properties: detail: description: Human-readable reason for the failure. title: Detail type: string required: - detail title: DetailErrorResponse type: object RequestValidationError: title: RequestValidationError type: object description: >- Returned when the request body, query string or path could not be parsed against the documented schema. Fix the listed fields and retry. properties: detail: type: array title: Detail description: One entry per invalid field. items: $ref: '#/components/schemas/RequestValidationErrorItem' required: - detail PublicCapacityDataSchema: description: 'Capacity payload: the evaluated range plus one entry per service.' properties: range: $ref: '#/components/schemas/PublicCapacityRangeSchema' description: The window that was evaluated. services: description: One entry per service in scope. items: $ref: '#/components/schemas/PublicCapacityServiceSchema' title: Services type: array required: - range title: PublicCapacityDataSchema type: object RequestValidationErrorItem: title: RequestValidationErrorItem type: object properties: loc: type: array title: Loc description: >- Where the problem is: the first element is `body`, `query` or `path`, followed by the field path. items: anyOf: - type: string - type: integer msg: type: string title: Msg description: What is wrong with the value. type: type: string title: Type description: >- Machine-readable validation error type, e.g. `missing` or `int_parsing`. required: - loc - msg - type PublicCapacityRangeSchema: description: The window that was actually walked. Dates are provider-local. properties: start_date: description: First date evaluated. format: date title: Start Date type: string end_date: description: Last date evaluated (inclusive). format: date title: End Date type: string days: description: Number of days in the range. title: Days type: integer required: - start_date - end_date - days title: PublicCapacityRangeSchema type: object PublicCapacityServiceSchema: description: A service's bookable room over the requested range. properties: id: description: Service ID (matches *List bookable services*). title: Id type: integer name: description: Service name. title: Name type: string duration_minutes: description: Fallback length for openings that declare no duration title: Duration Minutes type: integer capacity: description: >- Appointments that still fit, summed across the service's providers. An UPPER BOUND — booking one slot can eliminate more than one candidate once buffers interact. title: Capacity type: integer first_available_at: anyOf: - type: string - type: 'null' description: ISO-8601 UTC instant (…Z), or null when nothing fits title: First Available At effective_end_date: anyOf: - format: date type: string - type: 'null' description: >- Present only when the service's booking horizon (max_future_days) cut the requested range short. Absent means the full range was evaluated. title: Effective End Date days: description: Per-date breakdown across all providers. items: $ref: '#/components/schemas/PublicCapacityDaySchema' title: Days type: array profiles: anyOf: - items: $ref: '#/components/schemas/PublicCapacityProfileSchema' type: array - type: 'null' description: Per-provider breakdown; only with include=profiles title: Profiles required: - id - name - duration_minutes - capacity title: PublicCapacityServiceSchema type: object PublicCapacityDaySchema: description: Appointments that still fit on one PROVIDER-LOCAL date. properties: date: description: Provider-local calendar date (`YYYY-MM-DD`). format: date title: Date type: string capacity: description: Appointments that still fit on that date. title: Capacity type: integer required: - date - capacity title: PublicCapacityDaySchema type: object PublicCapacityProfileSchema: description: >- One provider's contribution to a service's capacity (``include=profiles``). properties: calendar_profile_id: description: Professional (calendar profile) ID. title: Calendar Profile Id type: integer name: description: Professional's display name. title: Name type: string timezone: description: IANA zone the provider's dates and slots are resolved in title: Timezone type: string duration_minutes: description: Appointment length the capacity was sized by. title: Duration Minutes type: integer capacity: description: Appointments that still fit for this professional. title: Capacity type: integer first_available_at: anyOf: - type: string - type: 'null' description: ISO-8601 UTC instant (…Z), or null when nothing fits title: First Available At days: description: Per-date breakdown for this professional. items: $ref: '#/components/schemas/PublicCapacityDaySchema' title: Days type: array required: - calendar_profile_id - name - timezone - duration_minutes - capacity title: PublicCapacityProfileSchema type: object securitySchemes: ApiKeyBearer: type: http scheme: bearer bearerFormat: pk_... description: >- API key created in the dashboard under **Settings → API Keys**. Send it as `Authorization: Bearer pk_...`. ````