> ## Documentation Index > Fetch the complete documentation index at: https://docs.fitsociety.io/llms.txt > Use this file to discover all available pages before exploring further. # List bookable availability slots > Requires `availability:read`. This is the final bookable availability feed for external client booking flows. It derives slots from calendar events, coach availability templates, location availability templates, closure days, booking rules, and optional client context. Filter with `clientId`, `eventTemplateId`, `eventTemplateIds`, `coachId`, `locationId`, and a maximum 31-day date range. Each slot includes a short-lived `availabilityToken` that can be submitted to `POST /public/v1/bookings`. Use the Availability Management endpoints to manage coach or location availability templates. ## OpenAPI ````yaml /openapi/public-v1.json get /public/v1/availability openapi: 3.1.0 info: title: FITsociety Public API v1 version: 1.0.0 description: >- Developer Public API endpoints under `/public/v1`. This reference is filtered to OAuth/Bearer Public API resources and excludes provider callback receivers, storefront routes, public widgets, wishlist routes, and access-device validation endpoints. contact: name: FITsociety Engineering servers: - url: https://api.fitsociety.io description: Production security: [] tags: - name: OAuth description: Public API OAuth endpoints for server-to-server client credentials. - name: Health description: Public API token health checks. - name: Platform description: >- Inspect Public API client context, capabilities, scopes, and redacted audit logs. - name: Company Catalog description: Read and manage company profile metadata and locations. - name: Clients description: >- Create and manage clients through the Public API using Bearer access tokens. - name: Coaches description: Retrieve coaches for the authenticated company via integrations. - name: Calendar Events description: Read Public API calendar events. - name: Calendar Templates description: >- Read and manage event types and event templates used by calendar availability and bookings. - name: Calendar Extensions description: >- Read recurring bookings, booking requests, calendar tasks, and availability closure metadata. - name: Availability description: Read bookable availability slots and signed availability tokens. - name: Availability Management description: >- Manage coach and location availability templates used to derive bookable slots. - name: Bookings description: Read and manage Public API bookings. - name: Finance description: >- Read invoices, payments, products, subscriptions, memberships, and credits with guarded finance writes. - name: Webhooks description: >- Manage outbound webhook subscriptions and inspect delivery attempts through Public API Bearer endpoints. - name: Measurements description: Read and write client measurement entries. - name: Progress Photos description: Read client progress photo metadata and short-lived signed media URLs. - name: Forms description: Read form metadata and submissions, and assign forms. - name: Documents description: Read document and folder metadata only. - name: Habits description: Read habits and habit entries. - name: Goals description: Read client goal summaries. - name: Messaging description: Read client chat and message metadata. - name: Reports description: Read aggregate attendance, revenue, and retention summaries. paths: /public/v1/availability: get: tags: - Availability summary: List bookable availability slots description: >- Requires `availability:read`. This is the final bookable availability feed for external client booking flows. It derives slots from calendar events, coach availability templates, location availability templates, closure days, booking rules, and optional client context. Filter with `clientId`, `eventTemplateId`, `eventTemplateIds`, `coachId`, `locationId`, and a maximum 31-day date range. Each slot includes a short-lived `availabilityToken` that can be submitted to `POST /public/v1/bookings`. Use the Availability Management endpoints to manage coach or location availability templates. operationId: getPublicV1Availability parameters: - name: dateFrom in: query required: true schema: type: string - name: dateTo in: query required: true schema: type: string - name: page in: query schema: type: integer minimum: 1 - name: limit in: query schema: type: integer minimum: 1 - name: clientId in: query schema: type: string - name: eventTemplateId in: query schema: type: string - name: eventTemplateIds in: query schema: type: string - name: coachId in: query schema: type: string - name: locationId in: query schema: type: string responses: '200': description: Availability fetched content: application/json: schema: allOf: - $ref: '#/components/schemas/PublicApiSuccessResponse' - type: object properties: data: type: object properties: dateFrom: type: string format: date-time dateTo: type: string format: date-time page: type: integer limit: type: integer total: type: integer totalPages: type: integer hasNextPage: type: boolean hasPrevPage: type: boolean slots: type: array items: type: object properties: slotId: type: string availabilityToken: type: string calendarEventId: type: - string - 'null' instanceDate: type: - string - 'null' format: date-time eventTemplateId: type: - string - 'null' name: type: string startAt: type: - string - 'null' format: date-time endAt: type: - string - 'null' format: date-time capacity: type: object properties: total: type: - number - 'null' booked: type: - number - 'null' remaining: type: - number - 'null' bookingMode: type: string enum: - bookable - waitlist_available - full - unavailable examples: success: summary: Successful response value: data: dateFrom: '2026-07-14T10:00:00.000Z' dateTo: '2026-07-14T10:00:00.000Z' page: 1 limit: 1 total: 1 totalPages: 1 hasNextPage: true hasPrevPage: true slots: - slotId: 66f7b8b1e13c8d25f4d3d90a availabilityToken: string calendarEventId: 66f7b8b1e13c8d25f4d3d90a instanceDate: '2026-07-14T10:00:00.000Z' eventTemplateId: 66f7b8b1e13c8d25f4d3d90a name: Example name startAt: '2026-07-14T10:00:00.000Z' endAt: '2026-07-14T10:00:00.000Z' capacity: total: 1 booked: 1 remaining: 1 bookingMode: bookable meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 '400': description: >- Bad request. The request shape, query, path parameter, or idempotency header is invalid. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: invalidRequest: summary: Invalid request value: error: code: 400 key: request.invalid message: The request is invalid. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 '401': description: >- Unauthorized. The Bearer token is missing, invalid, expired, or belongs to an inactive Public API client. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: missingBearer: summary: Missing Bearer token value: error: code: 401 key: auth.missing_bearer message: Authorization Bearer token is required. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 invalidToken: summary: Invalid or expired token value: error: code: 401 key: auth.invalid_token message: The access token is invalid or expired. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 invalidClient: summary: Inactive or revoked client value: error: code: 401 key: auth.invalid_client message: The Public API client is inactive or revoked. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 '403': description: >- Forbidden. The token is valid but does not include the required scope. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: insufficientScopes: summary: Missing required scope value: error: code: 403 key: scopes.insufficient message: The access token does not include the required scope. details: requiredScopes: - availability:read meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 '404': description: >- Not found. The requested company-scoped resource does not exist or is not accessible to this token. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: notFound: summary: Resource not found value: error: code: 404 key: resource.not_found message: The requested Public API resource was not found. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 '429': description: >- Too many requests. The Public API client or caller IP exceeded the rate limit. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: rateLimitExceeded: summary: Rate limit exceeded value: error: code: 429 key: rate_limit.exceeded message: Too many Public API requests. Retry later. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 0 resetSeconds: 1 retryAfterSeconds: 1 '500': description: >- Server error. The request could not be completed because of an unexpected Public API server failure. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: serverInternalError: summary: Unexpected server error value: error: code: 500 key: server.internal_error message: An unexpected Public API server error occurred. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 security: - PublicBearerAuth: [] x-codeSamples: - lang: cURL label: cURL source: |- curl -X GET "https://api.fitsociety.io/public/v1/availability" \ -H "Authorization: Bearer " components: schemas: PublicApiSuccessResponse: type: object additionalProperties: false required: - data - meta properties: data: type: object meta: $ref: '#/components/schemas/PublicApiMeta' PublicApiError: type: object additionalProperties: false required: - error - meta properties: error: type: object additionalProperties: false required: - code - key - message properties: code: type: integer example: 401 key: type: string example: auth.invalid_token message: type: string example: The access token is invalid. details: type: object additionalProperties: true meta: $ref: '#/components/schemas/PublicApiMeta' PublicApiMeta: type: object additionalProperties: false required: - requestId properties: requestId: type: string description: Stable request correlation id. Mirrors `X-Request-Id` when supplied. example: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: $ref: '#/components/schemas/PublicApiRateLimitMeta' PublicApiRateLimitMeta: type: object additionalProperties: false properties: limit: type: integer example: 10 remaining: type: integer example: 9 resetSeconds: type: integer description: Seconds until the current rate limit window resets. example: 1 retryAfterSeconds: type: integer description: Present when the request was rate limited. example: 1 securitySchemes: PublicBearerAuth: type: http scheme: bearer bearerFormat: Opaque description: >- Public API access token issued by `/public/v1/oauth/token`. Example: `Authorization: Bearer fspt_...`. ````