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

# Search available slots

> Returns the bookable slots for one appointment type in a time window, each with an opaque `slot_token`.

**Slots carry no provider identity.** The token seals the appointment type, the eligible providers, and the window; scheduling picks the provider when you book. Pass the token back verbatim — never parse or build one.

**Tokens are short-lived.** Each offer states its own deadlines: `expires_at` is the last moment it can be booked, `reservable_until` the last moment it can be held. Both are minutes away, so search again rather than caching offers.

**The window is capped at 30 days** and `from` must precede `to`. `state` is required only when the type has `requires_state_license` — retrieve the type to see whether it does.



## OpenAPI

````yaml /openapi.json get /slots
openapi: 3.1.0
info:
  title: OpenLoop API
  version: 0.1.0
  description: >-
    Unified reference for the OpenLoop Patient (clinical) and Payments & Revenue
    APIs.
servers:
  - url: https://api.openloophealth.com/v0.1
    description: Production partner edge
  - url: https://api-staging.openloophealth.com/v0.1
    description: Staging partner edge (sandbox credentials)
security: []
paths:
  /slots:
    get:
      tags:
        - Scheduling
      summary: Search available slots
      description: >-
        Returns the bookable slots for one appointment type in a time window,
        each with an opaque `slot_token`.


        **Slots carry no provider identity.** The token seals the appointment
        type, the eligible providers, and the window; scheduling picks the
        provider when you book. Pass the token back verbatim — never parse or
        build one.


        **Tokens are short-lived.** Each offer states its own deadlines:
        `expires_at` is the last moment it can be booked, `reservable_until` the
        last moment it can be held. Both are minutes away, so search again
        rather than caching offers.


        **The window is capped at 30 days** and `from` must precede `to`.
        `state` is required only when the type has `requires_state_license` —
        retrieve the type to see whether it does.
      parameters:
        - name: appointment_type_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
          description: The type to search availability for, from the bookable-types list.
        - name: from
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Inclusive start of the search window, as an ISO 8601 timestamp.
        - name: to
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: >-
            Exclusive end of the search window, as an ISO 8601 timestamp. At
            most 30 days after `from`.
        - name: state
          in: query
          required: false
          schema:
            type: string
            minLength: 2
            maxLength: 2
          description: >-
            Two-letter US state the visit takes place in. Required when the
            appointment type has `requires_state_license`; otherwise ignored.
        - name: patient_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: >-
            The patient the visit is for. Optional today and will become
            required, so send it whenever you have it. Required now when the
            appointment type is insurance-backed; omitting it then is a 400
            (`slot_search.patient_required`). When sent, a patient your
            organization does not manage, or that does not exist, is a 404
            (`patient.not_found`), and each offer's `slot_token` then books and
            reserves only this patient.
        - name: render_in_timezone
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 64
          description: >-
            IANA zone id (e.g. `America/Los_Angeles`). Adds `display_start_at` /
            `display_end_at` rendered in that zone; `start` and `end` stay UTC.
            An unknown zone is a 400 (`invalid_iana_timezone`).
        - name: cursor
          in: query
          required: false
          schema:
            type: string
            maxLength: 8192
            pattern: ^[A-Za-z0-9_-]+$
          description: >-
            Opaque `after` or `before` value from a previous response, passed
            back verbatim. It carries its own direction, so there is no separate
            paging parameter.
        - name: limit
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 1
              - type: string
                pattern: ^\d+$
            default: 25
          description: >-
            Maximum slots per page. Defaults to 25. There is no declared
            maximum, so a larger value is accepted rather than rejected, but the
            page size is capped at 50 — ask for more and you get 50. Values
            below 1 return `400`. The cap is lower here than on the other lists
            because every page mints one slot token per offer.
      responses:
        '200':
          description: A page of available slots.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/SchedulingSlotOffer'
                  after:
                    type: string
                    description: >-
                      Cursor for the next page. Absent only when there are no
                      further pages.
                  before:
                    type: string
                    description: >-
                      Cursor for the previous page. Absent on the first page of
                      a walk.
                  request_id:
                    type: string
                required:
                  - items
                  - request_id
        '400':
          description: >-
            Query validation failed. `code` distinguishes the cause:
            `slot_search.window_too_large`, `slot_search.window_invalid`,
            `slot_search.state_required`, `slot_search.patient_required`,
            `slot_search.cursor_invalid` (the cursor could not be decoded), or a
            field error carrying `invalid_iana_timezone`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/SchedulingProblem'
        '401':
          description: Missing or invalid bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/SchedulingProblem'
        '403':
          description: >-
            Authorization denied — your credentials do not carry the capability
            this endpoint requires, or the token's organization claim is not one
            you may act for.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/SchedulingProblem'
        '404':
          description: >-
            `slot_search.appointment_type_not_found` — the appointment type has
            no bookable slots configured; or `patient.not_found` — `patient_id`
            names a patient your organization does not manage, or one that does
            not exist.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/SchedulingProblem'
      security:
        - serviceToken: []
        - userToken: []
components:
  schemas:
    SchedulingSlotOffer:
      type: object
      description: >-
        One bookable slot. Carries no provider identity — the provider is chosen
        server-side at book time.
      properties:
        start:
          type: string
          format: date-time
          description: Slot start, UTC.
        end:
          type: string
          format: date-time
          description: Slot end, UTC.
        slot_token:
          type: string
          description: >-
            Opaque, self-contained, integrity-protected token sealing the
            appointment type, eligible providers, and window. Pass it verbatim
            to book, hold, or reschedule. Never parse it.
        expires_at:
          type: string
          format: date-time
          description: >-
            When the offer stops being bookable — `min(token TTL, slot start)`.
            Past it, book/hold/reschedule fail and you must search again.
        reservable_until:
          type: string
          format: date-time
          description: >-
            When the offer stops being reservable. Always at or before
            `expires_at`. Drop the offer from a reserve-first flow once this
            passes; booking directly stays allowed until `expires_at`.
        duration_minutes:
          type: integer
          exclusiveMinimum: 0
          description: >-
            Appointment length. Lets a UI tell apart two offers of the same type
            that differ only in duration.
        display_start_at:
          type: string
          description: >-
            `start` rendered in the requested zone. Present only when the
            request carried `render_in_timezone`.
        display_end_at:
          type: string
          description: >-
            `end` rendered in the requested zone. Present only when the request
            carried `render_in_timezone`.
      required:
        - start
        - end
        - slot_token
        - expires_at
        - reservable_until
        - duration_minutes
    SchedulingProblem:
      type: object
      description: >-
        RFC 7807 problem detail. Scheduling endpoints return errors as
        `application/problem+json`, not the platform `{ error, request_id }`
        envelope. `code` is the stable machine-readable identifier — branch on
        it, not on `detail`.
      properties:
        type:
          type: string
          description: Problem type URI. `about:blank` for the codes below.
        title:
          type: string
          description: Short human-readable summary, e.g. `Bad Request`.
        status:
          type: integer
          description: The HTTP status code, repeated in the body.
        detail:
          type: string
          description: Human-readable explanation of this occurrence.
        instance:
          type: string
        code:
          type: string
          description: >-
            Stable error identifier, e.g. `slot_search.window_too_large`,
            `appointment_list.offset_required`, `slot_token.tampered`.
          examples:
            - slot_search.window_too_large
        errors:
          type: array
          description: >-
            Field-level validation failures, when the error is a body/query
            validation failure.
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
              code:
                type: string
            required:
              - field
              - message
              - code
      required:
        - type
        - title
        - status
        - code
  securitySchemes:
    serviceToken:
      type: oauth2
      description: >-
        Service (M2M) access token issued by POST /auth/token using the
        client_credentials grant. Required scopes, where known, are listed on
        each operation below.
      flows:
        clientCredentials:
          tokenUrl: https://api.openloophealth.com/v0.1/auth/token
          scopes: {}
    userToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        User access token issued by POST /auth/token via the verification-code
        grant (after Verify a one-time code) or the refresh_token grant.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.