> ## Documentation Index > Fetch the complete documentation index at: https://docs.guile.app/llms.txt > Use this file to discover all available pages before exploring further. # List appointment openings for a date interval > List appointment openings for each calendar date in the requested interval. Dates with no openings, including closed days, appear with empty openings. Existing callers may provide `duration` to receive deployed regular-hours `openings`. New booking callers provide `serviceIds`; the server derives the duration and current service terms and returns legacy regular `openings`, exact `regularOffers`, and disjoint `offHoursQuotes`. When both are included, `serviceIds` is authoritative: the server ignores `duration` rather than validating it against the derived service duration. ## OpenAPI ````yaml /api-reference/Appointments/openapi.yaml get /openings/range openapi: 3.0.0 info: title: Appointments version: 0.1.0 contact: name: Guile Engineering url: https://www.guile.app email: engineering@guile.app license: name: MIT url: https://opensource.org/license/mit description: Appointment management servers: - url: https://api.guile.app variables: {} - url: https://guile.fly.dev variables: {} security: [] tags: - name: Recurring appointments description: Create and manage repeating visit series - name: Appointment management description: Barber-side confirm, decline, and cancel flows - name: Appointments description: Book, change, pay, and cancel visits paths: /openings/range: get: tags: - Appointments summary: List appointment openings for a date interval description: >- List appointment openings for each calendar date in the requested interval. Dates with no openings, including closed days, appear with empty openings. Existing callers may provide `duration` to receive deployed regular-hours `openings`. New booking callers provide `serviceIds`; the server derives the duration and current service terms and returns legacy regular `openings`, exact `regularOffers`, and disjoint `offHoursQuotes`. When both are included, `serviceIds` is authoritative: the server ignores `duration` rather than validating it against the derived service duration. operationId: listAppointmentOpeningsRange parameters: - name: locationId in: query required: true description: Limit openings to this specific location. schema: $ref: '#/components/schemas/resourceId' explode: false - name: barberId in: query required: false description: When included, limit openings to this specific barber. schema: $ref: '#/components/schemas/resourceId' explode: false - name: duration in: query required: false description: |- Calculate legacy regular openings for this appointment duration. Required when `serviceIds` is absent. Ignored when `serviceIds` is present because the server derives duration from current service terms. schema: type: string format: duration explode: false - name: serviceIds in: query required: false description: >- Select the services for server-derived regular opening offers and off-hours quotes. The server owns their price, duration, eligibility, exact occurrence, and availability; callers provide identifiers only. schema: type: array items: $ref: '#/components/schemas/resourceId' minItems: 1 maxItems: 25 explode: false style: pipeDelimited - name: dates in: query required: true description: |- Limit openings to the calendar dates in this range. The range names both its start and end dates and covers at most 31 calendar dates. schema: $ref: '#/components/schemas/dateRange' explode: false responses: '200': description: |- Ok. The operation succeeded. content: application/json: schema: $ref: '#/components/schemas/appointmentOpeningsRange' '400': description: >- Bad Request. The request body, request headers, and/or query parameters are not well-formed. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/badRequest](https://docs.guile.app/problems/badRequest) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' '401': description: >- Unauthorized. The operation requires authentication but no authentication or insufficient authentication was given. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/unauthorized](https://docs.guile.app/problems/unauthorized) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' '403': description: >- Forbidden. The authenticated caller is not authorized to perform the requested operation. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/forbidden](https://docs.guile.app/problems/forbidden) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' '404': description: >- Not Found. There is no such resource at the request URL. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/notFound](https://docs.guile.app/problems/notFound) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' '422': description: >- Unprocessable Entity. The request body and/or query parameters were well-formed but otherwise invalid. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/unprocessableEntity](https://docs.guile.app/problems/unprocessableEntity) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' '429': description: >- Too Many Requests. The client has sent too many requests in a given amount of time. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/tooManyRequests](https://docs.guile.app/problems/tooManyRequests) headers: Retry-After: required: true description: The number of seconds to wait before retrying the request. schema: type: integer format: uint32 content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' security: - BearerAuth: [] components: schemas: resourceId: type: string description: >- The unique, opaque system identifier for a resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference a resource by ID rather than URL. dateRange: type: string maxLength: 24 pattern: >- ^(\d{4}-\d{2}-\d{2}|[\[(](\d{4}-\d{2}-\d{2},(\d{4}-\d{2}-\d{2})?|,\d{4}-\d{2}-\d{2})[)\]])$ description: >- A date range, supporting inclusive or exclusive endpoints. Dates ranges use dates expressed in `YYYY-MM-DD` [RFC 3339](https://tools.ietf.org/html/rfc3339) `date` format. The value may have the following forms: - `YYYY-MM-DD` match the date exactly; equivalent to matching dates in the range `[YYYY-MM-DD,YYYY-MM-DD]` - `[YYYY-MM-DD,YYYY-MM-DD]` between two dates, inclusive of the endpoints - `(YYYY-MM-DD,YYYY-MM-DD)` between two dates, exclusive of the endpoints - `[YYYY-MM-DD,]` on or after the date - `(YYYY-MM-DD,)` after the date - `[,YYYY-MM-DD]` before or on the date - `(,YYYY-MM-DD)` before the date Examples: - '2022-05-19' - '[2022-05-01,2022-05-31]' - '[2022-05-01,2022-06-01)' - '[2022-05-19,]' - '(2022-05-19,)' - '[,2022-05-19]' - '(,2022-05-19)'. appointmentOpeningsRange: type: object required: - items - count - location - barber properties: items: type: array items: $ref: '#/components/schemas/dateOpenings' description: One entry per calendar date in the requested interval. count: type: integer format: int16 minimum: 0 description: The number of dates in the interval. This is derived and immutable. location: allOf: - $ref: '#/components/schemas/Common.ShopLocationReference' description: The shop location for the appointment openings. barber: allOf: - $ref: '#/components/schemas/Common.BarberReference' description: The barber for the appointment openings. bookableThrough: allOf: - $ref: '#/components/schemas/date' description: |- The furthest calendar date a client may book, based on the barber's advance booking window. When absent, booking is not limited by an advance window. description: |- Appointment openings grouped by calendar date over a requested interval. Every date in the interval appears exactly once; a date with no openings has an empty openings list and a count of zero. apiProblem: type: object required: - type - title - occurredAt - id - status properties: type: allOf: - $ref: '#/components/schemas/uri' description: A URI reference that identifies the problem type. title: type: string maxLength: 120 description: >- A short, human-readable summary of the problem type. The title is usually the same for all problems with the same `type`. occurredAt: type: string format: date-time description: >- The date-time when this problem occurred, in [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived and immutable. detail: type: string maxLength: 256 description: >- A human-readable explanation specific to this occurrence of the problem. id: allOf: - $ref: '#/components/schemas/resourceId' description: >- The unique identifier for this problem. This is an immutable opaque string. status: allOf: - $ref: '#/components/schemas/statusCode' description: >- The [HTTP status code](https://datatracker.ietf.org/doc/html/rfc7231#section-6)for this occurrence of the problem. instance: allOf: - $ref: '#/components/schemas/uri' maxLength: 2048 description: >- A URI reference that identifies the specific occurrence of the problem. This is the URI of an API resource that the problem is related to, with a unique error correlation ID URI fragment. attributes: type: object additionalProperties: {} description: >- Additional optional attributes related to the problem. This data conforms to the schema associated with the error type. recovery: allOf: - $ref: '#/components/schemas/clientFailureRecovery' description: The recovery contract for this problem occurrence. problems: type: array items: $ref: '#/components/schemas/problem' maxItems: 128 description: |- Optional root-causes if there are multiple problems in the request or API call processing. description: >- API problem or error response, as per [RFC 9457 application/problem+json](https://tools.ietf.org/html/rfc9457). dateOpenings: type: object required: - date - openings - count properties: date: allOf: - $ref: '#/components/schemas/date' description: The calendar date for these openings. openings: type: array items: $ref: '#/components/schemas/appointmentOpening' description: >- Regular-hours appointment opening times on this date. Off-hours times never appear in this list. regularOffers: type: array items: $ref: '#/components/schemas/regularAppointmentOpeningOffer' description: |- Short-lived exact regular-hours offers corresponding one-to-one with `openings`. Present only for service-scoped requests. offHoursQuotes: type: array items: $ref: '#/components/schemas/offHoursAppointmentQuote' description: |- Short-lived off-hours quotes, disjoint from `openings`. Absent for legacy duration-only requests. count: type: integer format: int16 minimum: 0 description: >- The number of regular-hours entries in `openings`. Off-hours quotes are excluded to preserve deployed count semantics. This is derived and immutable. description: Appointment openings for a single calendar date. Common.ShopLocationReference: type: object required: - id - name - shopName properties: id: allOf: - $ref: '#/components/schemas/resourceId' description: |- The unique identifier for this shop location reference. This is an immutable opaque string. name: type: string description: The name of this location for a shop. shopName: type: string description: The name of the shop business entity. description: |- A reference to a shop location. This contains a subset of properties for the location. Use ShopLocation for the full resource entity. Common.BarberReference: type: object required: - id - givenName - surname properties: id: allOf: - $ref: '#/components/schemas/resourceId' description: The unique identifier of the barber profile. givenName: type: string minLength: 1 maxLength: 55 format: text description: The given name of the barber. surname: type: string minLength: 1 maxLength: 55 format: text description: The surname of the barber. preferredName: type: string maxLength: 55 format: text description: The preferred name of the barber. biography: type: string maxLength: 2000 format: text description: A short biography of the barber. spokenLanguages: type: array items: $ref: '#/components/schemas/spokenLanguageTag' minItems: 1 description: Languages the barber speaks, as IETF BCP 47 language tags. experience: type: integer format: int32 minimum: 0 maximum: 100 description: |- Years of professional barbering experience. Omitted when the barber has not set a value. instagram: type: string minLength: 1 maxLength: 30 pattern: ^[A-Za-z0-9](?:[A-Za-z0-9._]{0,28}[A-Za-z0-9])?$ description: |- Public Instagram username for the booking page, without a leading @. Absent when unset. Not a private messaging channel. urlSlug: allOf: - $ref: '#/components/schemas/bookingSlug' description: The barber's public booking slug, used in profile links. profileImage_URL: type: string maxLength: 255 format: uri description: A URL to the barber's profile image. description: |- A reference to a barber resource. This contains a subset of properties for the barber. Use Barber for the full resource entity. date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- A date, expressed in `YYYY-MM-DD` [RFC 3339](https://tools.ietf.org/html/rfc3339) `date` format. uri: type: string maxLength: 1024 format: uri description: A URI reference to an internal or external resource. statusCode: type: integer format: uint16 minimum: 100 maximum: 599 description: The HTTP status code for a response. clientFailureRecovery: type: object required: - outcome - retry properties: outcome: allOf: - $ref: '#/components/schemas/clientFailureOutcome' description: The known outcome of the request. retry: allOf: - $ref: '#/components/schemas/clientRetryDirective' description: The safe retry action for the request. sessionAction: allOf: - $ref: '#/components/schemas/clientSessionAction' description: The session action required before the request can continue. rateLimit: allOf: - $ref: '#/components/schemas/rateLimit' description: The rate limit state that prevented the request. description: The recovery contract for a failed client request. problem: type: object required: - type - title - occurredAt - id - status properties: type: allOf: - $ref: '#/components/schemas/uri' description: A URI reference that identifies the problem type. title: type: string maxLength: 120 description: >- A short, human-readable summary of the problem type. The title is usually the same for all problems with the same `type`. occurredAt: type: string format: date-time description: >- The date-time when this problem occurred, in [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived and immutable. detail: type: string maxLength: 256 description: >- A human-readable explanation specific to this occurrence of the problem. id: allOf: - $ref: '#/components/schemas/resourceId' description: >- The unique identifier for this problem. This is an immutable opaque string. status: allOf: - $ref: '#/components/schemas/statusCode' description: >- The [HTTP status code](https://datatracker.ietf.org/doc/html/rfc7231#section-6)for this occurrence of the problem. instance: allOf: - $ref: '#/components/schemas/uri' maxLength: 2048 description: >- A URI reference that identifies the specific occurrence of the problem. This is the URI of an API resource that the problem is related to, with a unique error correlation ID URI fragment. attributes: type: object additionalProperties: {} description: >- Additional optional attributes related to the problem. This data conforms to the schema associated with the error type. description: >- Standard problem or error response, as per [RFC 9457 application/problem+json](https://tools.ietf.org/html/rfc9457). appointmentOpening: type: string description: The starting time for an appointment opening time slot, in 24 hour time. example: '9:00' regularAppointmentOpeningOffer: type: object required: - offerId - expiresAt - startsAt - occursOn - timeZone - barber - location - services - duration - serviceSubtotal properties: offerId: allOf: - $ref: '#/components/schemas/appointmentOpeningOfferId' description: |- An opaque, tamper-evident offer identifier. It binds the barber, location, selected services, exact occurrence, time zone, duration, service terms, internal authority revision, and expiry. expiresAt: type: string format: date-time description: When this offer expires. startsAt: allOf: - $ref: '#/components/schemas/appointmentOpening' description: The starting time for this opening in `timeZone`. occursOn: type: string format: date-time description: The exact occurrence represented by this offer, expressed in UTC. timeZone: allOf: - $ref: '#/components/schemas/ianaTimeZone' description: The IANA time zone used to calculate this opening. barber: allOf: - $ref: '#/components/schemas/Common.BarberReference' description: The barber this offer is bound to. location: allOf: - $ref: '#/components/schemas/Common.ShopLocationReference' description: The location this offer is bound to. services: type: array items: $ref: '#/components/schemas/appointmentOpeningServiceTerm' minItems: 1 maxItems: 25 description: The server-owned selected service terms this offer is bound to. duration: type: string format: duration description: The server-owned total duration of the selected services. serviceSubtotal: allOf: - $ref: '#/components/schemas/money' description: |- The server-owned subtotal for the selected services, excluding fees, tips, taxes, and platform fees. description: >- A short-lived offer for one exact regular-hours appointment occurrence. The offer does not reserve capacity. Appointment creation atomically revalidates the barber, location, services, occurrence, time zone, schedule, booking window, service terms, and conflicts before persisting. Repeating the winning request with the same idempotency key returns the original result. Another request losing the same-slot race returns `appointmentSlotUnavailable`. offHoursAppointmentQuote: type: object required: - quoteId - expiresAt - startsAt - occursOn - timeZone - barber - location - services - duration - serviceSubtotal - band - approvalMode properties: quoteId: allOf: - $ref: '#/components/schemas/offHoursAppointmentQuoteId' description: >- An opaque, tamper-evident quote identifier. It binds the barber, location, selected services, occurrence, time zone, opening band, fee, approval requirement, internal policy revision, and expiry. The identifier may be redeemed once. expiresAt: type: string format: date-time description: When this quote expires. startsAt: allOf: - $ref: '#/components/schemas/appointmentOpening' description: The starting time for this opening in `timeZone`. occursOn: type: string format: date-time description: The exact occurrence represented by this quote, expressed in UTC. timeZone: allOf: - $ref: '#/components/schemas/ianaTimeZone' description: The IANA time zone used to calculate this opening. barber: allOf: - $ref: '#/components/schemas/Common.BarberReference' description: The barber this quote is bound to. location: allOf: - $ref: '#/components/schemas/Common.ShopLocationReference' description: The location this quote is bound to. services: type: array items: $ref: '#/components/schemas/offHoursAppointmentServiceTerm' minItems: 1 maxItems: 25 description: The server-owned selected service terms this quote is bound to. duration: type: string format: duration description: The server-owned total duration of the selected services. serviceSubtotal: allOf: - $ref: '#/components/schemas/money' description: |- The server-owned subtotal for the selected services, excluding the off-hours fee, tips, taxes, and platform fees. band: allOf: - $ref: '#/components/schemas/offHoursAppointmentOpeningBand' description: The off-hours band this quote belongs to. offHoursFee: allOf: - $ref: '#/components/schemas/money' description: >- The off-hours fee for this opening. When absent, no off-hours fee applies. Creating an appointment from this quote does not authorize or capture the fee; Guile settles it only after the barber confirms the appointment. approvalMode: allOf: - $ref: '#/components/schemas/offHoursAppointmentApprovalMode' description: Off-hours appointments always require barber approval. description: >- A short-lived quote for an off-hours appointment opening. The quote does not reserve the opening before create. Appointment creation atomically revalidates availability, service eligibility, price, and approval policy, consumes the quote, and persists a pending appointment that consumes the scarce capacity. One same-slot or same-quote race has one winner. Repeating the winning request with the same idempotency key returns the original result. Reusing a consumed quote with another key returns `offHoursQuoteAlreadyUsed`. A different quote or actor losing the same-slot race returns `appointmentSlotUnavailable`. spokenLanguageTag: type: string enum: - ar - de - en - es - fr - ko - ru - tl - vi - zh description: An IETF BCP 47 language tag supported on barber profiles. bookingSlug: type: string minLength: 3 maxLength: 40 pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ description: A barber's public booking slug, used in profile links. clientFailureOutcome: type: string enum: - notApplied - unknown description: The known outcome of a failed client request. clientRetryDirective: type: string enum: - doNotRetry - retrySameRequest - retrySameRequestAfterDelay description: The safe retry action for a failed client request. clientSessionAction: type: string enum: - refresh - signIn description: The session action required before a failed request can continue. rateLimit: type: object required: - limit - remaining - resetsAt properties: limit: type: integer format: uint64 description: The maximum number of requests allowed in the active window. remaining: type: integer format: uint64 description: The number of requests remaining in the active window. resetsAt: type: string format: date-time description: >- The date-time when the active window resets, in [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. description: The rate limit state for the request. appointmentOpeningOfferId: type: string minLength: 1 maxLength: 2048 description: >- An opaque, tamper-evident identifier for an exact regular appointment opening offer. ianaTimeZone: type: string description: An IANA time-zone identifier. appointmentOpeningServiceTerm: type: object required: - id - name - cost - duration properties: id: allOf: - $ref: '#/components/schemas/resourceId' description: The selected service identifier. name: type: string minLength: 1 description: The current customer-facing service name. cost: allOf: - $ref: '#/components/schemas/money' description: The current service price, excluding fees, tips and taxes. duration: type: string format: duration description: The current service duration. description: >- Server-owned service terms captured by a regular appointment opening offer. money: type: string pattern: ^-?(0|[1-9][0-9]*)\.[0-9][0-9]$ format: decimal description: >- A monetary amount in the lowest denomination for the given currency. The numeric value is represented as a string so that it can be exact with no loss of precision. Values may be positive or negative. example: '456.78' offHoursAppointmentQuoteId: type: string minLength: 1 maxLength: 2048 description: An opaque, tamper-evident identifier for an off-hours appointment quote. offHoursAppointmentServiceTerm: type: object required: - id - name - cost - duration properties: id: allOf: - $ref: '#/components/schemas/resourceId' description: The selected service identifier. name: type: string minLength: 1 description: The current customer-facing service name. cost: allOf: - $ref: '#/components/schemas/money' description: The current service price, excluding fees, tips and taxes. duration: type: string format: duration description: The current service duration. description: Server-owned service terms captured by an off-hours quote. offHoursAppointmentOpeningBand: type: string enum: - beforeHours - afterHours description: Which off-hours band an appointment opening belongs to. offHoursAppointmentApprovalMode: type: string enum: - required description: The approval behavior for an off-hours appointment quote. securitySchemes: BearerAuth: type: http scheme: Bearer ````