> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gridbeds.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List reservations
> Returns up to 50 of the organization's reservations, the most recently created first. Requires the `reservations.read` scope.
## OpenAPI
````yaml /openapi/integration-v1.json get /v1/integration/reservations
openapi: 3.1.2
info:
title: Gridbeds Integration API
version: 2.0.0
description: >-
The Gridbeds public integration API. Authenticate with a scoped Bearer token
issued to your installed app; every request is isolated to that app's
organization.
termsOfService: https://gridbeds.com/en/terms/
contact:
name: Gridbeds support
email: support@gridbeds.com
license:
name: Proprietary
url: https://gridbeds.com/en/terms/
servers:
- url: https://api.gridbeds.com/api
description: Production
- url: https://staging-api.gridbeds.com/api
description: Sandbox
security:
- bearerAuth: []
tags:
- name: Identity
description: >-
Who the token belongs to: the installation, its organization and the
scopes it was granted.
- name: Reservations
description: The organization's reservations.
- name: Guests
description: The organization's guest profiles, which a reservation is made for.
paths:
/v1/integration/reservations:
get:
tags:
- Reservations
summary: List reservations
description: >-
Returns up to 50 of the organization's reservations, the most recently
created first. Requires the `reservations.read` scope.
operationId: listReservations
responses:
'200':
description: Up to 50 reservations, the most recently created first.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ReservationListItem'
required:
- data
'401':
description: >-
Unauthenticated: the token is missing, unknown or revoked. A user's
own sign-in token is refused the same way.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: >-
Forbidden. The token was not granted the `reservations.read` scope,
or its installation is disabled or in error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: >-
Too many requests: an installation may make 120 per minute. Wait
`Retry-After` seconds.
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
headers:
Retry-After:
description: Seconds until the next request is counted afresh.
schema:
type: integer
X-RateLimit-Limit:
description: Requests allowed in the window.
schema:
type: integer
X-RateLimit-Remaining:
description: 'Requests left in the window: 0 here.'
schema:
type: integer
X-RateLimit-Reset:
description: When the window ends, as a Unix timestamp.
schema:
type: integer
components:
schemas:
ReservationListItem:
type: object
properties:
id:
type: string
format: uuid
description: The reservation's id.
organization_id:
type: string
format: uuid
description: >-
The organization the record belongs to: always the one that
installed the app.
status:
$ref: '#/components/schemas/BookingStatus'
description: >-
Where the reservation stands in its life.
| |
|---|
| `pending`
Received and waiting to be confirmed. |
| `confirmed`
Confirmed by the property. |
| `option`
Held for the guest until the hold expires or the
property confirms it. The room is held meanwhile. |
| `cancelled`
Cancelled. The room is free again. |
| `no_show`
The guest did not arrive. The room is free again.
|
| `checked_in`
The guest has arrived and is staying. |
| `checked_out`
The guest has left. |
check_in:
type: string
format: date-time
description: >-
The arrival date. A calendar date, sent as a timestamp at midnight
UTC
(`2026-10-24T00:00:00.000000Z`): the time carries no meaning, read
the date part.
check_out:
type: string
format: date-time
description: The departure date, sent the way `check_in` is.
total_price:
type: string
description: >-
The total price of the stay as a decimal string with two digits, in
`currency`.
currency:
type:
- string
- 'null'
description: >-
The ISO 4217 code the prices are in. `null` only in the response to
creating a
reservation that named no currency: it then has its default
currency, which every
later read returns.
required:
- id
- organization_id
- status
- check_in
- check_out
- total_price
- currency
title: ReservationListItem
Error:
type: object
description: The body of a refused request.
properties:
message:
type: string
description: >-
What went wrong, in a sentence for a person. Do not match on it: the
wording can change and follows the request's language.
code:
type: string
description: >-
A stable identifier of the refusal, present when it has one, such as
`idempotency_key_reused`. Match on this.
errors:
type: object
description: >-
Present on a validation failure: the messages for each field that
failed, keyed by field name.
additionalProperties:
type: array
items:
type: string
required:
- message
title: Error
RateLimitError:
type: object
description: The body of a request refused for exceeding the installation's quota.
properties:
error:
type: string
description: Always `Too Many Requests`.
message:
type: string
description: What happened, in a sentence for a person.
retry_after:
type: integer
description: Seconds to wait before the next request.
required:
- error
- message
- retry_after
title: RateLimitError
BookingStatus:
type: string
description: >-
Booking status enumeration. Represents the possible states of a booking
in the system.
| |
|---|
| `pending`
Received and waiting to be confirmed. |
| `confirmed`
Confirmed by the property. |
| `option`
Held for the guest until the hold expires or the
property confirms it. The room is held meanwhile. |
| `cancelled`
Cancelled. The room is free again. |
| `no_show`
The guest did not arrive. The room is free again. |
| `checked_in`
The guest has arrived and is staying. |
| `checked_out`
The guest has left. |
enum:
- pending
- confirmed
- option
- cancelled
- no_show
- checked_in
- checked_out
title: BookingStatus
securitySchemes:
bearerAuth:
type: http
description: >-
An integration token, sent as `Authorization: Bearer `.
A token belongs to one installation of an app. Someone at the property
who may manage its integrations installs the app in Gridbeds, under
Settings → Integrations, and issues the token there, granting the scopes
the app requested or a subset of them. The token is shown once; issuing
a new one revokes the previous one.
Every request reads and writes the data of the organization that
installed the app, and nothing else. Each operation names the scope it
requires. A token without that scope, and the token of an installation
that is disabled or in error, are refused with 403; a token that is
missing, unknown or revoked, and a user's own sign-in token, are refused
with 401.
scheme: bearer
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.