> ## Documentation Index
> Fetch the complete documentation index at: https://docs.os.default.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get available slots
> Returns bookable start times in [start, end) for the event. The range must end after it starts and may span up to 63 days, nine weeks from whatever start you choose, about two months of availability per request. Page further ranges with the same reservationId. When no reservationId is supplied a new reservation is created and returned. Pass it to [`POST /v1/scheduling/meetings`](/api-reference/scheduling/book-a-meeting) to book.
Requires the `scheduling:read` scope.
Reuse the returned reservationId when querying additional date ranges — it pins host selection so paged results stay consistent, and avoids minting a reservation per request.
## OpenAPI
````yaml /api-reference/openapi.json post /v1/scheduling/events/{event}/slots
openapi: 3.1.0
info:
title: Default Public API
version: 1.0.0
description: >-
Customer-facing REST API for scheduling and workflow triggers: list events,
fetch availability, book, reschedule, or cancel meetings, and fire API
triggers. Authenticate every request with `Authorization: Bearer `
using an API key created in workspace settings (Settings → API Keys). Keys
carry permissions (`scheduling:read`, `scheduling:write`, `triggers:read`,
`triggers:write`; a write key also satisfies read for its surface) and can
be revoked at any time. Requests are rate limited to 30 per minute per key —
a 429 response carries a `Retry-After` header with the seconds until the
window resets. This is a server-to-server API: no CORS headers are sent, so
it cannot be called directly from a browser.
servers:
- url: https://api.default.com
security:
- apiKey: []
paths:
/v1/scheduling/events/{event}/slots:
post:
tags:
- Scheduling
summary: Get available slots
description: >-
Returns bookable start times in [start, end) for the event. The range
must end after it starts and may span up to 63 days, nine weeks from
whatever start you choose, about two months of availability per request.
Page further ranges with the same reservationId. When no reservationId
is supplied a new reservation is created and returned. Pass it to [`POST
/v1/scheduling/meetings`](/api-reference/scheduling/book-a-meeting) to
book.
Requires the `scheduling:read` scope.
operationId: getEventSlots
parameters:
- name: event
in: path
required: true
description: >-
An event id or slug returns times for the event's own hosts. A
scheduling link id or slug, like the schedulingLinkId from a fired
trigger, returns times for the hosts the link was routed to. A link
slug wins over an event slug with the same value.
schema:
description: >-
An event id or slug returns times for the event's own hosts. A
scheduling link id or slug, like the schedulingLinkId from a fired
trigger, returns times for the hosts the link was routed to. A
link slug wins over an event slug with the same value.
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
reservationId:
type: string
format: uuid
required:
- start
- end
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
reservationId:
type: string
format: uuid
eventId:
type: string
format: uuid
expiresAt:
type: string
slots:
type: array
items:
type: string
activeHost:
anyOf:
- type: object
properties:
name:
anyOf:
- type: string
- type: 'null'
profilePictureUrl:
anyOf:
- type: string
- type: 'null'
hostIsQueue:
type: boolean
required:
- name
- profilePictureUrl
- hostIsQueue
additionalProperties: false
- type: 'null'
required:
- reservationId
- eventId
- expiresAt
- slots
- activeHost
additionalProperties: false
'400':
description: Error (INVALID_REQUEST, RESERVATION_MISMATCH)
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- INVALID_REQUEST
- RESERVATION_MISMATCH
message:
type: string
details:
type: array
items:
type: string
examples:
INVALID_REQUEST:
summary: INVALID_REQUEST
value:
error:
code: INVALID_REQUEST
message: Request validation failed
details:
- 'personEmail: Invalid email address'
RESERVATION_MISMATCH:
summary: RESERVATION_MISMATCH
value:
error:
code: RESERVATION_MISMATCH
message: Reservation does not match this event
'401':
description: Error (INVALID_API_KEY)
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- INVALID_API_KEY
message:
type: string
details:
type: array
items:
type: string
examples:
INVALID_API_KEY:
summary: INVALID_API_KEY
value:
error:
code: INVALID_API_KEY
message: Missing, malformed, or revoked API key
'403':
description: Error (MISSING_SCOPE)
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- MISSING_SCOPE
message:
type: string
details:
type: array
items:
type: string
examples:
MISSING_SCOPE:
summary: MISSING_SCOPE
value:
error:
code: MISSING_SCOPE
message: >-
This API key is missing the required 'scheduling:read'
scope
'404':
description: Error (NOT_FOUND)
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- NOT_FOUND
message:
type: string
details:
type: array
items:
type: string
examples:
NOT_FOUND:
summary: NOT_FOUND
value:
error:
code: NOT_FOUND
message: Event not found
'409':
description: Error (RESERVATION_EXPIRED, RESERVATION_USED, NO_HOST_AVAILABLE)
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- RESERVATION_EXPIRED
- RESERVATION_USED
- NO_HOST_AVAILABLE
message:
type: string
details:
type: array
items:
type: string
examples:
RESERVATION_EXPIRED:
summary: RESERVATION_EXPIRED
value:
error:
code: RESERVATION_EXPIRED
message: >-
Reservation has expired — request slots again to get a
new one
RESERVATION_USED:
summary: RESERVATION_USED
value:
error:
code: RESERVATION_USED
message: >-
Reservation has already been used — an earlier booking
attempt may have succeeded, so confirm before booking
again
NO_HOST_AVAILABLE:
summary: NO_HOST_AVAILABLE
value:
error:
code: NO_HOST_AVAILABLE
message: >-
No host is available at the selected time — pick another
slot
'429':
description: Error (RATE_LIMITED)
headers:
Retry-After:
description: Seconds until the current rate-limit window resets.
schema:
type: integer
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- RATE_LIMITED
message:
type: string
details:
type: array
items:
type: string
examples:
RATE_LIMITED:
summary: RATE_LIMITED
value:
error:
code: RATE_LIMITED
message: Rate limit exceeded for this API key
'500':
description: Error (INTERNAL_ERROR)
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- INTERNAL_ERROR
message:
type: string
details:
type: array
items:
type: string
examples:
INTERNAL_ERROR:
summary: INTERNAL_ERROR
value:
error:
code: INTERNAL_ERROR
message: Internal server error
components:
securitySchemes:
apiKey:
type: http
scheme: bearer
description: >-
Organization API key, created in workspace settings (Settings → API
Keys). Sent as `Authorization: Bearer `. Shown once at creation;
revocable and permission-scoped per key.
````