> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lobbystack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List open appointment times

> Open start times for one service, in 30-minute steps within opening hours. The range can span up to 7 days.



## OpenAPI

````yaml /api-reference/openapi.json get /availability
openapi: 3.1.0
info:
  title: LobbyStack API
  version: v1
  description: >-
    Read calls, contacts, appointments and messages, book appointments, and
    subscribe to webhooks. Authenticate with an API key in the Authorization
    header. Each key allows 120 requests per minute by default.
servers:
  - url: https://app.lobbystack.com/api/v1
security:
  - bearerAuth: []
tags:
  - name: Business
  - name: Calls
  - name: Contacts
  - name: Appointments
  - name: Messages
  - name: Knowledge
  - name: Webhooks
paths:
  /availability:
    get:
      tags:
        - Appointments
      summary: List open appointment times
      description: >-
        Open start times for one service, in 30-minute steps within opening
        hours. The range can span up to 7 days.
      operationId: getAvailability
      parameters:
        - name: service_id
          in: query
          required: true
          description: The service to book.
          schema:
            type: string
            format: uuid
        - name: start_date
          in: query
          required: true
          description: First day, YYYY-MM-DD, in the business time zone.
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          description: Last day, YYYY-MM-DD. Defaults to start_date.
          schema:
            type: string
            format: date
        - name: staff_id
          in: query
          description: Only times this active staff member is free.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - next_cursor
                  - has_more
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AvailabilitySlot'
                  next_cursor:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Pass as cursor to get the next page. Null on the last
                      page.
                  has_more:
                    type: boolean
        '400':
          description: The request is invalid (invalid_request).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid, or revoked (unauthorized).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The API key lacks the appointments:read scope (insufficient_scope).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Too many requests (rate_limited). Wait for the Retry-After header's
            number of seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait.
      security:
        - bearerAuth: []
components:
  schemas:
    AvailabilitySlot:
      type: object
      properties:
        starts_at:
          description: ISO 8601 timestamp in UTC.
          type: string
          format: date-time
        ends_at:
          description: ISO 8601 timestamp in UTC.
          type: string
          format: date-time
      required:
        - starts_at
        - ends_at
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - invalid_request
                - unauthorized
                - forbidden
                - insufficient_scope
                - not_found
                - conflict
                - idempotency_key_reused
                - idempotency_request_in_progress
                - booking_disabled
                - booking_requires_confirmation
                - slot_unavailable
                - rate_limited
                - rate_limit_unavailable
                - method_not_allowed
                - internal_error
            message:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  path:
                    type: string
                  message:
                    type: string
                required:
                  - path
                  - message
                additionalProperties: false
          required:
            - code
            - message
          additionalProperties: false
      required:
        - error
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An API key from Settings > API keys. Scopes: business:read,
        business:write, calls:read, contacts:read, contacts:write,
        appointments:read, appointments:write, messages:read, knowledge:write,
        webhooks:manage.

````