Integration API - Gridbeds

The Gridbeds Integration API lets an app work with the reservations and guests of the organization that installed it. Every page under Endpoints is generated from the API’s OpenAPI document, the same file the API is built and checked against, and its playground sends real requests. The base URL of production is https://api.gridbeds.com/api, and every path starts with /v1/integration/. The playground’s server menu also offers the sandbox.

Authentication

Send an integration token on every request:

Authorization: Bearer <token>

A token belongs to one installation of an app. Someone at the property who may manage its integrations connects the app in Gridbeds, under Settings → Integrations (App marketplace), 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. Each operation names the scope it requires:

Scope	Operations
none	Get the calling installation
`reservations.read`	List reservations, Get a reservation
`reservations.write`	Create a reservation
`guests.read`	List guests
`guests.write`	Create a guest

Start with Get the calling installation: it answers with the installation, its organization, its status, the app and the scopes the token was granted, and requires no scope.

One organization per token

Every request reads and writes the data of the organization that installed the app, and nothing else. A record of another organization answers 404, exactly as one that does not exist.

Errors

A refused request answers with a JSON body:

Field
`message`	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`	A stable identifier of the refusal, present when it has one, such as `idempotency_key_reused`. Match on this.
`errors`	On a validation failure: the messages for each field that failed, keyed by field name.

Status	When
401	The token is missing, unknown or revoked, or is a user’s own sign-in token.
403	The token was not granted the operation’s scope, or its installation is disabled or in error.
404	There is no such record in the token’s organization.
409	The first request with this `Idempotency-Key` is still being processed (`idempotency_in_flight`). Retry shortly.
422	The request failed validation, or asks for something the organization cannot do (`code` says what).
429	The installation exceeded its rate limit.

Rate limits

An installation may make 120 requests per minute. Beyond that the API answers 429 with a Retry-After header, the seconds to wait, beside X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (when the window ends, as a Unix timestamp). The body carries error, message and retry_after.

Retrying a create safely

Create a reservation and Create a guest accept an Idempotency-Key header. For at least 24 hours, the same key with the same body answers with the first response instead of creating a second record. The same key with a different body is refused with 422 (idempotency_key_reused).

Versions

The version of the API is in the path: /v1/. The reference shows the version of the OpenAPI document; a change that would break a client already built against it, such as a removed operation or response field or a request field that became required, is published only as a new major version of the document.

Identity

Who the token belongs to: the installation, its organization and its scopes.

Reservations

List, read and create the organization’s reservations.

Guests

List and create the guest profiles a reservation is made for.

​Authentication

​One organization per token

​Errors

​Rate limits

​Retrying a create safely

​Versions