API reference

Stay n Host has a REST API, the same one the app itself uses. Every endpoint is described in an OpenAPI 3.1 document that anyone can read, so you can browse it, generate a client from it, or load it into a tool such as Postman.

The document: https://app.staynhost.com/api/openapi.json

It describes shapes only - paths, parameters, request and response bodies. It contains no data from any workspace.

The basics


Base path	`https://app.staynhost.com/api/v1`
Format	JSON in, JSON out
Authentication	An API key, sent as a Bearer token
Who can use it	Workspaces on Operator or Enterprise (API access)

Authenticate with an API key

Create a key on Setup → API keys (Admins), ticking only the permissions it needs, then send it in the Authorization header of every request:

GET /api/v1/... HTTP/1.1
Host: app.staynhost.com
Authorization: Bearer lodgr_ab12cd34ef56_…

Keys start with lodgr_. The whole key is shown once, when you create it. Step by step, and what a key can never do: Connect other systems with API keys.

What a key may do is decided on every request:

Its permissions (scopes) - only what you ticked when you made it.
Its creator’s permissions today - a key can never do more than the person who made it can do now. If their role loses a permission, the key loses it at the same moment; if their seat is removed, the key stops working. A seat limited to some properties gives its keys the same limit.
The creator’s phone - while the key’s creator has no phone number confirmed by a text-message code, every request is refused with phone_required. They fix it by signing in to the app and confirming the number (Sign in and confirm your phone).
People-only actions - verifying payments, approving refunds, releasing door codes and creating or revoking keys always need a signed-in person, so a key cannot do them.

Errors

Every error has the same JSON body:

{ "error": { "code": "phone_required", "message": "Confirm your phone number to continue." } }

Status	Common `code`	Meaning
`401`	`unauthenticated`	No key, or a key that is revoked, expired, or whose creator has left the workspace.
`403`	`forbidden`, `phone_required`	The key was not given this permission, its creator does not hold it, or the creator has not confirmed a phone number.
`404`	`not_found`	The record does not exist in your workspace - or the endpoint belongs to a feature your plan does not include.
`429`	`rate_limited`	Too many requests. Keys are limited to about one request a second, with short bursts allowed. Wait and retry.

Some errors add a detail with a more specific reason.

Get told when something changes

Rather than asking the API over and over, let Stay n Host call you: webhooks send a signed message to your URL when bookings, payments, guests or cleaning change.

Every change is on the record

Each write made with a key appears in the audit trail with the key’s prefix, so you can tell an integration’s change from a person’s.