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

# Read a complete operational schedule

> Required offset-bearing starts_from and starts_before select overlapping visits or internal-event occurrences (exclusive end), for at most 31 days. Page at most 100 complete items, ordered by earliest start (millisecond precision), ID and kind. Visits include all assignments even outside the time or member filter. Default canceled=false; canceled=true selects canceled visits only and excludes internal events. Business-unit, job-type and job-class filters select visits only. Recurring events preserve company-local time, until bounds and exception days. Reads exceeding 5000 selected visits, event series or occurrences fail explicitly. No snapshot, availability or deletion-feed guarantee.



## OpenAPI

````yaml /openapi.json get /schedule
openapi: 3.0.3
info:
  title: Breezy Public API
  version: 1.0.0
  description: >-
    Read customers, team members, jobs, visits, assignments, installed
    equipment, captured form responses, time entries, configured-period
    timesheets, business reference catalogs, job leads, estimates, invoices,
    payments, refunds, recorded job financials, saved sold/earned credits, and
    financial summaries for your company. Read the operational schedule and
    create, edit, cancel and assign visits. Existing API keys grant company-wide
    reads and scheduling writes. Customer notifications require an explicit
    request per operation. Amounts are integer USD cents. Reads return current
    corrected records, with cursor pagination for collecting results.


    Read the [Breezy FSM guides](https://developers.getbreezyapp.com) for
    authentication, pagination, refresh limits, and business measures. All reads
    use latest corrected company records; cursors do not create a snapshot or a
    complete change feed.
servers:
  - url: https://api.getbreezyapp.com/v1
    description: Breezy FSM production API
security:
  - apiKey: []
tags:
  - name: Scheduling
  - name: Company
  - name: Invoices
  - name: Payments
  - name: Refunds
  - name: Reports
  - name: TeamMembers
  - name: Accounts
  - name: Contacts
  - name: Locations
  - name: Jobs
  - name: JobAppointments
  - name: JobAssignments
  - name: BusinessUnits
  - name: JobTypes
  - name: JobClasses
  - name: JobLifecycles
  - name: LeadSources
  - name: Tags
  - name: Estimates
  - name: JobLeads
  - name: Equipment
  - name: FormResponses
  - name: TimeEntries
  - name: Timesheets
  - name: JobFinancials
  - name: RevenueAttributions
externalDocs:
  description: Breezy FSM reporting guides and API reference
  url: https://developers.getbreezyapp.com
paths:
  /schedule:
    get:
      tags:
        - Scheduling
      summary: Read a complete operational schedule
      description: >-
        Required offset-bearing starts_from and starts_before select overlapping
        visits or internal-event occurrences (exclusive end), for at most 31
        days. Page at most 100 complete items, ordered by earliest start
        (millisecond precision), ID and kind. Visits include all assignments
        even outside the time or member filter. Default canceled=false;
        canceled=true selects canceled visits only and excludes internal events.
        Business-unit, job-type and job-class filters select visits only.
        Recurring events preserve company-local time, until bounds and exception
        days. Reads exceeding 5000 selected visits, event series or occurrences
        fail explicitly. No snapshot, availability or deletion-feed guarantee.
      operationId: getSchedule
      parameters:
        - schema:
            type: string
            format: date-time
          required: true
          name: starts_from
          in: query
        - schema:
            type: string
            format: date-time
          required: true
          name: starts_before
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          required: false
          name: limit
          in: query
        - schema:
            type: string
            nullable: true
            maxLength: 4096
            default: null
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            nullable: true
            format: uuid
            default: null
          required: false
          name: team_member_id
          in: query
        - schema:
            type: string
            nullable: true
            format: uuid
            default: null
          required: false
          name: business_unit_id
          in: query
        - schema:
            type: string
            nullable: true
            format: uuid
            default: null
          required: false
          name: job_type_id
          in: query
        - schema:
            $ref: '#/components/schemas/NullableJobClass'
          required: false
          name: job_class
          in: query
        - schema:
            type: boolean
            default: false
          required: false
          name: canceled
          in: query
      responses:
        '200':
          description: Successful read. Clients ignore unrecognized response fields.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchedulePage'
              example:
                data:
                  - id: 11111111-1111-4111-8111-000000001109
                    number: '300'
                    job_id: 11111111-1111-4111-8111-000000000501
                    type: Other
                    description: Air conditioner repair visit
                    window_start_at: '2026-09-08T19:00:00Z'
                    window_end_at: '2026-09-08T21:00:00Z'
                    confirmed: false
                    canceled: false
                    cancellation_reason: null
                    cancellation_note: null
                    created_by:
                      id: 11111111-1111-4111-8111-000000000401
                      name: Alex Example
                    created_at: '2026-08-19T16:00:00Z'
                    updated_at: '2026-09-08T19:00:00Z'
                    kind: APPOINTMENT
                    starts_at: '2026-09-08T19:00:00Z'
                    ends_at: '2026-09-08T21:00:00Z'
                    revision: >-
                      aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
                    job:
                      id: 11111111-1111-4111-8111-000000000501
                      number: '200'
                      summary: Repair air conditioner
                      account:
                        id: 11111111-1111-4111-8111-000000000101
                        name: Example Household
                      location:
                        id: 11111111-1111-4111-8111-000000001107
                        name: Home
                        address: 123 Example Lane, Los Angeles, CA 90001
                        latitude: 34.02
                        longitude: -118.25
                      contact:
                        id: 11111111-1111-4111-8111-000000001101
                        name: Jordan Example
                      business_unit:
                        id: 11111111-1111-4111-8111-000000000201
                        name: Service
                      job_type:
                        id: 11111111-1111-4111-8111-000000000301
                        name: HVAC Service
                      job_class: SERVICE
                    assignments:
                      - id: 11111111-1111-4111-8111-000000001113
                        job_id: 11111111-1111-4111-8111-000000000501
                        appointment_id: 11111111-1111-4111-8111-000000001109
                        team_member:
                          id: 11111111-1111-4111-8111-000000000401
                          name: Alex Example
                        starts_at: '2026-09-08T19:30:00Z'
                        ends_at: '2026-09-08T20:30:00Z'
                        status: TO_DO
                        status_updated_at: '2026-09-08T18:00:00Z'
                        created_at: '2026-08-19T16:00:00Z'
                        updated_at: null
                      - id: 11111111-1111-4111-8111-000000002001
                        job_id: 11111111-1111-4111-8111-000000000501
                        appointment_id: 11111111-1111-4111-8111-000000001109
                        team_member:
                          id: 11111111-1111-4111-8111-000000002002
                          name: Sam Example
                        starts_at: '2026-09-08T19:30:00Z'
                        ends_at: '2026-09-08T20:30:00Z'
                        status: TO_DO
                        status_updated_at: '2026-09-08T18:00:00Z'
                        created_at: '2026-08-19T16:00:00Z'
                        updated_at: null
                    dispatch_status: ASSIGNED
                  - id: 11111111-1111-4111-8111-000000002003
                    number: UNASSIGNED1
                    job_id: 11111111-1111-4111-8111-000000000501
                    type: Other
                    description: Air conditioner repair visit
                    window_start_at: '2026-09-08T19:00:00Z'
                    window_end_at: '2026-09-08T21:00:00Z'
                    confirmed: false
                    canceled: false
                    cancellation_reason: null
                    cancellation_note: null
                    created_by:
                      id: 11111111-1111-4111-8111-000000000401
                      name: Alex Example
                    created_at: '2026-08-19T16:00:00Z'
                    updated_at: '2026-09-08T19:00:00Z'
                    kind: APPOINTMENT
                    starts_at: '2026-09-08T19:00:00Z'
                    ends_at: '2026-09-08T21:00:00Z'
                    revision: >-
                      aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
                    job:
                      id: 11111111-1111-4111-8111-000000000501
                      number: '200'
                      summary: Repair air conditioner
                      account:
                        id: 11111111-1111-4111-8111-000000000101
                        name: Example Household
                      location:
                        id: 11111111-1111-4111-8111-000000001107
                        name: Home
                        address: 123 Example Lane, Los Angeles, CA 90001
                        latitude: 34.02
                        longitude: -118.25
                      contact:
                        id: 11111111-1111-4111-8111-000000001101
                        name: Jordan Example
                      business_unit:
                        id: 11111111-1111-4111-8111-000000000201
                        name: Service
                      job_type:
                        id: 11111111-1111-4111-8111-000000000301
                        name: HVAC Service
                      job_class: SERVICE
                    assignments: []
                    dispatch_status: UNASSIGNED
                  - kind: INTERNAL_EVENT
                    id: 11111111-1111-4111-8111-000000002004
                    starts_at: '2026-09-08T23:00:00Z'
                    ends_at: '2026-09-09T01:00:00Z'
                    team_member_ids:
                      - 11111111-1111-4111-8111-000000000401
                    reason: TRAINING
                    description: Evening training
                    recurrence_rule: FREQ=WEEKLY;BYDAY=TU
                pagination:
                  next_cursor: null
                meta:
                  request_id: 11111111-1111-4111-8111-000000009999
                  generated_at: '2026-09-08T19:00:00Z'
                  timezone: America/Los_Angeles
        '400':
          description: >-
            Malformed input, unknown query parameter, unsupported combination or
            invalid cursor.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: INVALID_REQUEST
                  message: end_date must be later than start_date
                  request_id: example-request
                  details: []
        '401':
          description: Missing, invalid or expired key, or invalid linked identity.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
            WWW-Authenticate:
              schema:
                type: string
              example: Bearer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UNAUTHENTICATED
                  message: A valid API key is required
                  request_id: example-request
                  details: []
        '404':
          description: >-
            Missing resource or resource outside the authenticated company. Same
            response for both.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: NOT_FOUND
                  message: Resource not found
                  request_id: example-request
                  details: []
        '405':
          description: >-
            Unsupported methods return 405. See the operation list for supported
            scheduling writes.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
            Allow:
              schema:
                type: string
              example: GET, HEAD, OPTIONS
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: METHOD_NOT_ALLOWED
                  message: This resource supports GET
                  request_id: example-request
                  details: []
        '409':
          description: >-
            Stale revision, idempotency-key reuse with different input,
            scheduling conflict, or unsupported stored recurrence. Inspect
            error.code.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: STALE_REVISION
                  message: The visit changed; read it again before editing
                  request_id: example-request
                  details: []
        '413':
          description: Request body is too large.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: INVALID_REQUEST
                  message: Request body exceeds 64 KB
                  request_id: example-request
                  details: []
        '429':
          description: Company request budget exhausted; retry after the indicated delay.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Seconds before retrying.
              example: 30
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: RATE_LIMITED
                  message: Request limit exceeded
                  request_id: example-request
                  details: []
        '500':
          description: >-
            Unexpected failure. Share request_id with support; no stack or
            provider secrets in response.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: Unable to complete request
                  request_id: example-request
                  details: []
      security:
        - apiKey: []
components:
  schemas:
    NullableJobClass:
      type: string
      nullable: true
      enum:
        - SERVICE
        - MAINTENANCE
        - ESTIMATE_REPAIR
        - ESTIMATE_REPLACE
        - INSTALL
        - WARRANTY
        - CALLBACK
        - SALES
        - UNKNOWN
        - null
    SchedulePage:
      type: object
      properties:
        data:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/ScheduleAppointment'
              - $ref: '#/components/schemas/ScheduleEventOccurrence'
            discriminator:
              propertyName: kind
              mapping:
                APPOINTMENT:
                  $ref: '#/components/schemas/ScheduleAppointment'
                INTERNAL_EVENT:
                  $ref: '#/components/schemas/ScheduleEventOccurrence'
        pagination:
          $ref: '#/components/schemas/Pagination'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      required:
        - data
        - pagination
        - meta
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - INVALID_REQUEST
                - INVALID_CURSOR
                - SCHEDULE_TOO_LARGE
                - INVALID_SCHEDULE_EVENT
                - SCHEDULE_CONFLICT
                - STALE_REVISION
                - IDEMPOTENCY_CONFLICT
                - UNAUTHENTICATED
                - NOT_FOUND
                - METHOD_NOT_ALLOWED
                - RATE_LIMITED
                - INTERNAL_ERROR
            message:
              type: string
            request_id:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - field
                  - message
          required:
            - code
            - message
            - request_id
            - details
      required:
        - error
    ScheduleAppointment:
      allOf:
        - $ref: '#/components/schemas/JobAppointment'
        - type: object
          properties:
            kind:
              type: string
              enum:
                - APPOINTMENT
            starts_at:
              type: string
              format: date-time
              description: Earliest start of the arrival window and its assignments.
            ends_at:
              type: string
              format: date-time
              description: Latest end of the arrival window and its assignments.
            revision:
              type: string
              description: >-
                Opaque version of this visit and its complete assignments; use
                for conditional writes.
            job:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                number:
                  type: string
                summary:
                  type: string
                  nullable: true
                account:
                  $ref: '#/components/schemas/Reference'
                location:
                  type: object
                  nullable: true
                  properties:
                    id:
                      type: string
                      format: uuid
                    name:
                      type: string
                      nullable: true
                    address:
                      type: string
                      nullable: true
                    latitude:
                      type: number
                      nullable: true
                    longitude:
                      type: number
                      nullable: true
                  required:
                    - id
                    - name
                    - address
                    - latitude
                    - longitude
                contact:
                  $ref: '#/components/schemas/NullableReference'
                business_unit:
                  $ref: '#/components/schemas/NullableReference'
                job_type:
                  $ref: '#/components/schemas/NullableReference'
                job_class:
                  $ref: '#/components/schemas/NullableJobClass'
              required:
                - id
                - number
                - summary
                - account
                - location
                - contact
                - business_unit
                - job_type
                - job_class
            assignments:
              type: array
              items:
                $ref: '#/components/schemas/JobAssignment'
              description: >-
                Complete set of this visit's company-owned assignments,
                including outside the requested period or technician filter.
            dispatch_status:
              type: string
              enum:
                - CANCELED
                - UNASSIGNED
                - ASSIGNED
                - EN_ROUTE
                - IN_PROGRESS
                - COMPLETED
          required:
            - kind
            - starts_at
            - ends_at
            - revision
            - job
            - assignments
            - dispatch_status
    ScheduleEventOccurrence:
      type: object
      properties:
        kind:
          type: string
          enum:
            - INTERNAL_EVENT
        id:
          type: string
          format: uuid
          description: >-
            Internal-event series ID. Pair with starts_at to identify an
            occurrence.
        starts_at:
          type: string
          format: date-time
        ends_at:
          type: string
          format: date-time
        team_member_ids:
          type: array
          items:
            type: string
            format: uuid
        reason:
          type: string
          enum:
            - NOT_SCHEDULED
            - LUNCH
            - BREAK
            - ON_CALL
            - PERSONAL_APPOINTMENT
            - INTERNAL_MEETING
            - TRAINING
            - PTO
            - HOLIDAY
            - OUT_SICK
            - SHOP_WORK
            - SUPPLY_PARTS_PICKUP
            - OTHER
        description:
          type: string
          nullable: true
        recurrence_rule:
          type: string
          nullable: true
      required:
        - kind
        - id
        - starts_at
        - ends_at
        - team_member_ids
        - reason
        - description
        - recurrence_rule
    Pagination:
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
          description: >-
            Opaque continuation. Null ends traversal. Keep the same filters;
            page size may change.
      required:
        - next_cursor
    ResponseMeta:
      type: object
      properties:
        request_id:
          type: string
        generated_at:
          type: string
          format: date-time
        timezone:
          type: string
      required:
        - request_id
        - generated_at
        - timezone
      description: >-
        Generation time and company timezone. generated_at is not a snapshot or
        synchronization token.
    JobAppointment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        number:
          type: string
        job_id:
          type: string
          format: uuid
        type:
          type: string
        description:
          type: string
          nullable: true
        window_start_at:
          type: string
          format: date-time
        window_end_at:
          type: string
          format: date-time
        confirmed:
          type: boolean
        canceled:
          type: boolean
        cancellation_reason:
          type: string
          nullable: true
        cancellation_note:
          type: string
          nullable: true
        created_by:
          $ref: '#/components/schemas/NullableReference'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          description: >-
            Parent record edit time only; related records may change
            independently.
      required:
        - id
        - number
        - job_id
        - type
        - description
        - window_start_at
        - window_end_at
        - confirmed
        - canceled
        - cancellation_reason
        - cancellation_note
        - created_by
        - created_at
        - updated_at
    Reference:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
      required:
        - id
        - name
    NullableReference:
      type: object
      nullable: true
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
      required:
        - id
        - name
    JobAssignment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        job_id:
          type: string
          format: uuid
        appointment_id:
          type: string
          format: uuid
        team_member:
          $ref: '#/components/schemas/Reference'
        starts_at:
          type: string
          format: date-time
        ends_at:
          type: string
          format: date-time
        status:
          type: string
          nullable: true
          enum:
            - TO_DO
            - EN_ROUTE
            - IN_PROGRESS
            - COMPLETED
            - CANCELED
            - null
        status_updated_at:
          type: string
          nullable: true
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          description: >-
            Unavailable: assignment edits do not maintain a parent update
            timestamp.
          nullable: true
          enum:
            - null
      required:
        - id
        - job_id
        - appointment_id
        - team_member
        - starts_at
        - ends_at
        - status
        - status_updated_at
        - created_at
        - updated_at
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        Existing Breezy API key. Grants all published reads and scheduling
        writes in its associated company. No app permission scopes.

````