# Session feed for directories and developers

> How sauna directories, apps and AI assistants can list a venue's upcoming sessions and availability from its free session feed, with every field explained and the terms of use.

Every venue on Session can publish a free session feed: a JSON file of its upcoming sessions, their availability and a link to book each one. Directories, apps, AI assistants and web designers can read it instead of the booking page. This page is for you, the person building on it.

<Callout variant="note">
Feeds are starting soon. Until then the addresses below return "Not found".
</Callout>

## Where the feed is

For a booking page at `bookasession.org/harbour-sauna`:

- `https://bookasession.org/harbour-sauna/sessions.json` - the next 14 days.
- `https://bookasession.org/harbour-sauna/sessions/2026-12.json` - one whole month. Each file's `months` list says which months exist (this month and the next five). Follow it rather than building month names.

`https://bookasession.org/llms.txt` lists venues on Session (up to 200). A venue that has turned its feed off, or isn't live yet, answers `404`. If a file can't be rebuilt, the last good copy keeps being served.

There is no key and no sign-up. Files update within a few minutes of a booking or a schedule change. Browsers can read them from any website (`Access-Control-Allow-Origin: *`).

## What's in it

```json
{
  "version": 1,
  "venue": {
    "name": "Harbour Sauna",
    "slug": "harbour-sauna",
    "url": "https://bookasession.org/harbour-sauna",
    "currency": "GBP",
    "timezone": "Europe/London",
    "display": { "spaces": "always", "duration": "end_time", "show_name": true, "show_location": false, "clock": "24h" }
  },
  "generated_at": "2026-11-23T09:00:00.000Z",
  "horizon_end": "2026-12-07T09:00:00.000Z",
  "months": ["2026-11", "2026-12", "2027-01", "2027-02", "2027-03", "2027-04"],
  "truncated": false,
  "session_types": [
    {
      "id": "6f1c...",
      "name": "Sunrise sauna",
      "description": ["Wood-fired sauna and a cold plunge in the harbour."],
      "image_url": "https://...",
      "image_focal": { "x": 0.5, "y": 0.4 },
      "category": { "name": "Sauna" },
      "price_from_minor": 1200,
      "url": "https://bookasession.org/harbour-sauna/sunrise-sauna?utm_source=feed"
    }
  ],
  "sessions": [
    {
      "id": "a83e...",
      "name": "Sunrise sauna",
      "location": { "id": "51b0...", "name": "Harbour wall" },
      "type_id": "6f1c...",
      "start": "2026-11-24T07:00:00+00:00",
      "end": "2026-11-24T08:00:00+00:00",
      "timezone": "Europe/London",
      "time_label": "07:00 - 08:00",
      "availability": "few_left",
      "spaces_left": 2,
      "booking_closes_at": "2026-11-24T06:00:00+00:00",
      "booking_url": "https://bookasession.org/harbour-sauna/sunrise-sauna?t=...&utm_source=feed"
    }
  ]
}
```

**Each session**

- `availability` is `available`, `few_left`, `full` (its link leads to a waiting list) or `closed` (booking has closed for that date).
- `privately_booked: true` means one group has booked the whole session. It's `full` with no waiting list, so show it as fully booked, without a link.
- `spaces_left` appears only when the venue's booking page shows a count, so treat it as optional.
- `start` and `end` carry the session's own UTC offset, and `timezone` names its zone. Show times in that zone, never the visitor's.
- `time_label` and `duration_label` are the time and length exactly as the booking page prints them, such as `6:00 - 7:15pm`, or `13:00 or 13:30` with `30-60m`.
- Some sessions let customers choose a length: `lengths_minutes` lists them (`[45, 75]`). Others sell part of a session: `shortest_minutes`, `longest_minutes` and `later_starts` (when else a booking can begin) say so.
- `name` can be a date and time when the venue left the session unnamed. Then `untitled` is `true`, and showing the time alone reads best.
- `private_hire: true` means the session is only sold to a group booking the whole of it.
- `location` is `null` when the venue hasn't given the session a location.
- `description_override` replaces the type's `description` for that one date.
- `booking_url` is the only way to book. Link every session to it.

**Each session type** is listed once in `session_types`, and sessions point to it with `type_id`. `name` can be `null`. `description` is plain-text paragraphs, never HTML. `image_focal` is the point to keep in view when cropping, from 0 to 1. `price_from_minor` is the lowest price on the session page in the smallest unit of `venue.currency` (`1200` is £12.00), and is left out when it's free, can't be worked out, or the type is private hire only. It's a guide: the session page shows the real prices.

**`venue.display`** says how the venue's own booking page shows sessions: `spaces` (`always`, `nearly_full` or `never`, already applied to `spaces_left`), `duration` (`end_time`, `minutes` or `never`), `show_name`, `show_location` and `clock` (`12h` or `24h`). Follow it to match the venue's page. A venue on `duration: never` doesn't publish how long sessions last, so lengths are left out and you should not show the end time.

**The file**: `truncated` is `true` if a very busy venue had more sessions than one file holds (1,000). `horizon_end` is when `sessions.json` stops. A month file also has `month` (such as `2026-12`) and lists that whole month. Sessions that have started, are hidden, are only for members yet, or are offered by request aren't included.

## Changes to the feed

`version` is `1`. New fields may be added at any time, so ignore ones you don't know. A field is never renamed, removed or changed in meaning without a new `version` at a new address, and notice to anyone who has told us they use the feed.

## Terms of use

Using the feed means you agree to these terms, which sit alongside our [terms of service](https://bookasession.org/terms-of-service).

1. **Link to book.** Every session you show links to its `booking_url`. You may change `utm_source=feed` to your own name so the venue can see bookings you send. Don't take bookings, payments or customer details for the venue yourself.
2. **Fetch politely.** Fetch each file no more than once every five minutes, from your own server where you can. Send a `User-Agent` that names your service and a contact address.
3. **Keep it current.** Refresh at least once a day. Remove sessions that leave the feed, and stop listing a venue whose feed answers `404` - it has turned the feed off.
4. **Show it as it is.** Don't change times, prices or availability, or show a full or closed session as bookable. Say when you convert a price to another currency.
5. **Use the venue's words and pictures only for its sessions.** Names, descriptions and images belong to the venue. Use them to list its sessions, beside a link to book.
6. **Use only the feed.** Reading booking pages or anything else on Session automatically is not allowed (section 4 of the terms of service).
7. **No endorsement.** Don't suggest that Session or a venue partners with or recommends you unless they've said so in writing.
8. **No guarantee.** The feed is free and provided as it is. The booking page is always the final word on what can be booked. We can change these terms, and block access that breaks them.

Questions, or want to hear about changes? Email [wil@bookasession.org](mailto:wil@bookasession.org).

## Common questions

1. **Can I show sessions from every venue on Session?** Yes, any venue whose feed answers, on these terms. Venues can turn the feed off at any time.

2. **Can people book without leaving my site?** No. Booking and payment happen on the venue's booking page, where its own cancellation rules apply.

3. **I'm a venue's web designer. Is there a ready-made schedule?** Yes, the [website schedule](/docs/website-schedule) renders this feed as plain HTML you can style.
