API reference

Keys

An admin makes a key under Settings → API keys, gives it a name that says what will use it, and chooses how long it lasts: 30 days, 90 days, a year, or until it is removed. The key is shown once, when it is made. We keep only a scrambled copy of it, so we cannot show it again: if it is lost, remove it and make another.

Each key reads one bunkhouse and no other. Make one for each thing you connect, so that you can remove one without the others. Removing a key stops it working at once, and so does switching off, or taking away the admin role from, the admin who made it.

A key sees guests’ names, email addresses, phone numbers and notes only if that was ticked when it was made. Without it, a booking is its dates, its party, its rooms and its money, and the email log is closed to it. A program you give guests’ details to is one you are sharing them with, so choose one you trust with them.

Sending the key

The API is at /api/v1/ on your bunkhouse’s own booking address, the one guests book at. Send the key with every request, in the Authorization header:

curl https://yours.bunkhouse.page/api/v1/bookings \
  -H "Authorization: Bearer bkh_…"

Never put a key in the address: addresses are written into logs. A request that does is refused, and the key should be replaced.

Answers are JSON. Money is in whole pence, dates are 2026-10-12, and times are UTC, as 2026-10-12T09:30:00Z.

Errors and limits

Every error has the same shape: a code a program can act on, and a message a person can read.

{
  "error": {
    "code": "bad_key",
    "message": "That key is not one of this bunkhouse's…"
  }
}

What it reads

GET /api/v1/bunkhouse

The bunkhouse: its name and contact details, its time zone, check-in and check-out times, its rooms and their beds, today’s date where it is, how far ahead guests can book, and whether it is in test mode.

GET /api/v1/bookings

Bookings, newest first, 50 at a time. next is the address of the next page, or null when there is none; the last full page can lead to an empty one. Narrow it with:

• from and to: bookings with a night in between, to being the morning after the last night.
• status: confirmed, completed, cancelled, no_show or pending (a guest part way through paying).
• q: the booking’s reference, or with guests’ details the guest’s name, email or phone too.
• limit: up to 200 at a time.

Each booking has its reference, status, arrival and departure, nights, adults and children, how it was booked, the total, what is paid and what is owed and when, and a link to its page in the staff pages.

GET /api/v1/bookings/{ref}

One booking, with its priced lines, its payments and refunds, the rooms and beds it has each night, and its history: who did what, and when. What each change was is given only to a key with guests’ details, since it can name them. A line staff added by hand says what they wrote, or, to a key without guests’ details, only that staff added it; and to such a key, who did each thing is only staff, support, guest or system.

GET /api/v1/days/{date}

A day as the dashboard has it: who is arriving, who is leaving, who is staying the night, how many people that is, and how many beds are free. Arriving and staying count confirmed bookings, and those a guest is part way through paying for; leaving counts those and completed ones. today is today where the bunkhouse is.

GET /api/v1/availability?from=…&to=…

Beds free in each room, each night, up to 92 nights at a time.

GET /api/v1/payments?from=…&to=…

Every payment and refund recorded on those days, up to 366 days at a time, oldest first, with the booking each is for, and the totals taken, refunded, and still owed back. A refund’s pence are below nought; one agreed but not yet sent back has the status owed.

GET /api/v1/emails

The emails sent to guests and staff, newest first, 50 to a page: what each was, who it went to, and whether it was delivered. Their words are not included. Only a key with guests’ details may read it; q searches the addresses and subjects.

GET /api/v1/key

The key itself: its name, what it may read, who made it, the bunkhouse it reads, and when it runs out.

Connecting an AI assistant

An assistant that can make web requests, such as Claude Code, needs only the address and a key. Keep the key out of the conversation itself: put it where the assistant’s tools can read it, as an environment variable, and tell it this page is the reference. For example:

export BUNKHOUSE_API=https://yours.bunkhouse.page/api/v1
export BUNKHOUSE_KEY=bkh_…

Read https://bunkhouse.page/docs/api/. Using $BUNKHOUSE_API with the
key in $BUNKHOUSE_KEY, tell me who arrives this weekend, and which
bookings still owe a balance.

For the people who run BunkhousePage

The platform has an API of its own at https://bunkhouse.page/api/v1/, read with an operator’s key (bkho_…) made at /admin/keys. It works only while whoever made it is an operator.

• GET /api/v1/bunkhouses: every bunkhouse, with its state, fee, Stripe account, staff numbers, bookings, money and email health.
• GET /api/v1/bunkhouses/{id}: one, with its staff by role, its latest payments through Stripe and emails, and what needs a look.
• GET /api/v1/key: the key itself.

This API names nobody: it gives a bunkhouse’s figures, its payments through Stripe, how many staff it has and in what roles, and what kind of email it sent, with every address cut down to its domain. Its bookings are not an operator’s to read, unless a member of its staff turns on support access from their profile. While it is on, the bunkhouse’s own API can be read through the platform: /api/v1/bunkhouses/{id}/bookings is its /api/v1/bookings, and so on for each part of it. It reads as a key without guests’ details does, and the email log too, with every address cut down to its domain and no search. support_access_until says whether it is on, and until when. Each read is written to our server’s log, and shown to the staff who let support in as when it was last used.