The content API gives your website the content a hotel keeps in ChannelRUSH: its description, contact details,
photos in the order the hotel arranged them, room types, restaurants and other venues, FAQs, events, blog posts and
pages. Use it to build a home page with a photo slider, a page per room type, a restaurant page, and so on. When the
hotel changes a photo or a description in ChannelRUSH, your pages pick it up within about a minute.

The API is read-only. Bookings go through the [booking widget](https://help.channelrush.com/hc/channelrush/articles/booking-widget), which uses the same key.

## Which API to use

| You are building | Use |
|---|---|
| The hotel's own website (pages, photos, room and venue pages) | **This content API**, with the hotel's booking widget key |
| Booking on that website | The [booking widget](https://help.channelrush.com/hc/channelrush/articles/booking-widget), with the same key |
| A distribution or travel-agent integration that books and reads reservations from your server | The [CRS API](https://help.channelrush.com/hc/channelrush/articles/crs-api) (a token for a whole channel; never put it in a web page) |

## Key and access

Use the property's booking widget key (`pk_live_…`). The hotel issues one in ChannelRUSH → Admin → CRS Settings →
Booking Widgets and lists the web addresses of its site on it. A key is for one property. The same page's "How to use
a key" panel shows these requests and the property's room type and rate plan ids.

Send the key in the `X-CR-Key` header with every request:

```
GET https://be.channelrush.net/v1/content?lang=en-US
X-CR-Key: pk_live_xxxxxxxxxxxx
```

- **From a browser** (a `fetch` in your page): the page's address must be on the key's list, as for the widget.
  Otherwise the answer is `403 origin_denied`.
- **From your server or a build step**: send no `Origin` and no `Referer` header. Content calls are accepted without
  them. Booking calls never are.
- **Test keys** (`pk_test_…`) work only from `localhost`.

The key is public by design: anyone can read a hotel's public content on its website. It cannot book, cancel or read
reservations through this API.

## Answers

Every answer is JSON in an envelope:

```json
{ "ok": true, "data": { … }, "error": null, "requestId": "0HN…" }
{ "ok": false, "data": null, "error": { "code": "not_found", "message": "Room type not found.", "details": null }, "requestId": "0HN…" }
```

Field names are camelCase. A field with no value is `null` or `""`; it is never left out. Ids are strings.

## Endpoints

All endpoints take `lang` (for example `en-US` or `de-DE`). Without it you get the property's default language. A
language the property does not offer falls back to the same language in another region, then to the default.
`data.language` (on `GET /v1/content`) says which one you got, and `data.languages` lists the others.

| Request | Returns |
|---|---|
| `GET /v1/content` | The property, its home-page sections, and a short card for each room type, venue and page |
| `GET /v1/content/rooms/{id}` | One room type: description, facts, amenities, photos, rate plans, add-ons |
| `GET /v1/content/venues/{id}` | One venue (a restaurant, a spa, …): description, address, contacts, amenities, photos |
| `GET /v1/content/posts?page=1` | The published blog posts, newest first, 10 a page |
| `GET /v1/content/posts/{slug}` | One post with its HTML |
| `GET /v1/content/pages/{id}` | One page (About, a custom page, a legal page) with its HTML |

Fetch `GET /v1/content` once for the site's structure, then fetch the room, venue, post or page each page shows.

### `GET /v1/content`

```json
{
  "language": "en-US",
  "languages": [{ "code": "en-US", "name": "English (United States)" }],
  "property": {
    "id": "1700", "name": "Hotel San Marina", "tagline": "By the sea",
    "descriptionShort": "…", "descriptionLong": "<p>…</p>",
    "address": { "street": "1 Water St", "city": "…", "stateProv": "…", "postalCode": "…", "countryCode": "US" },
    "phone": "+1 555 0100", "email": "reservations@…", "contactEmail": "hello@…",
    "map": { "latitude": 21.3, "longitude": -157.8, "url": "https://goo.gl/maps/…" },
    "timeZoneId": "Pacific/Honolulu", "checkInTime": "15:00", "checkOutTime": "11:00",
    "stars": 4, "numberOfRooms": 40, "amenities": ["Pool", "Spa"],
    "logo": { … }, "photos": [{ … }, { … }],
    "social": { "facebook": "", "instagram": "https://instagram.com/…", "twitter": "", "youTube": "", "pinterest": "", "flickr": "" }
  },
  "sections": {
    "faq": [{ "question": "Is parking free?", "answer": "Yes." }],
    "team": [{ "name": "…", "role": "…", "bio": "…", "photo": null }],
    "counters": [{ "value": 25, "suffix": "+", "label": "years by the sea" }],
    "features": [{ "title": "Free Wi-Fi", "text": "…", "icon": "wifi", "photo": null }],
    "events": [{ "title": "Jazz night", "startDate": "2026-11-02", "endDate": null, "summary": "…", "linkUrl": "", "photo": { … } }],
    "video": { "provider": "youTube", "videoId": "…", "title": "…", "caption": "…", "embedUrl": "https://www.youtube-nocookie.com/embed/…", "poster": null }
  },
  "rooms": [{ "id": "1808121", "slug": "deluxe-double-42", "name": "Deluxe Double", "occupancyMax": 2, "photo": { … } }],
  "venues": [{ "id": "429031", "name": "Ocean Grill", "type": "restaurant", "photo": { … } }],
  "pages": [{ "id": "30360", "type": "about", "name": "About us", "menuName": "About", "path": "/about" }],
  "postCount": 3
}
```

- `descriptionLong` is written in a rich text editor and may hold HTML. Everything else in `property` and `sections`
  is plain text; line breaks separate paragraphs.
- `sections` holds what the hotel's own booking site shows today. Events drop off the day after they end; a section
  with nothing in it is an empty list (or `null` for `video`).
- `video.embedUrl` is a privacy-friendly player address. Load it in an `<iframe>` when the visitor clicks, not before.
- `venues[].type` is `restaurant` or `other`.

### `GET /v1/content/rooms/{id}`

```json
{
  "id": "1808121", "slug": "deluxe-double-42", "name": "Deluxe Double",
  "description": "…", "beds": "1 King bed", "bedCount": 1,
  "occupancyMin": 1, "occupancyMax": 2, "size": { "value": 32, "unit": "sqm" },
  "bathrooms": 1, "bedrooms": null, "smoking": false,
  "amenities": ["Desk", "Balcony"], "photos": [{ … }],
  "ratePlans": [{ "id": "453553", "name": "Best available rate", "description": "…" }],
  "addOns": [{ "id": "88", "name": "Breakfast", "description": "…", "included": true, "photos": [] }]
}
```

- `size` is `null` when the hotel has not entered one; `unit` is `sqm` or `sqft`.
- `occupancyMax` is `null` when the room type has no limit set.
- `addOns[].included` is `true` for what the rate includes (for example breakfast) and `false` for an extra the guest
  can buy while booking.
- A room type that is switched off, or that has no content in the language, answers `404 not_found`.

### Venues, posts and pages

- **Venue:** `id`, `name`, `type`, `description`, `address`, `phone`, `email`, `amenities`, `photos`. Only venues the
  hotel has set up and switched on are listed.
- **Post list:** `page`, `pageCount`, `total`, and `posts` (`slug`, `title`, `summary`, `category`, `publishDate`,
  `hero`). A post shows from its publish date.
- **Post:** the same fields plus `html`.
- **Page:** `id`, `type` (`about`, `contact`, `custom`, `legalPrivacyPolicy`, …), `name`, `menuName`, `path` (its
  address on the hotel's booking site), `html`.

**About the HTML.** `html` (posts and pages) and `descriptionLong` are written by the hotel in ChannelRUSH's rich
text editor and sent exactly as stored. They are not cleaned. Put them through your own HTML sanitiser if your site
needs one.

## Photos

Every photo has the same shape:

```json
{ "url": "https://…", "thumbUrl": "https://…", "largeUrl": "https://…", "alt": "Pool at dusk", "width": 4000, "height": 2667 }
```

- `url` is 980 px wide, for a page or a slider.
- `thumbUrl` is cropped to 320 × 240.
- `largeUrl` is 1600 px wide, for a lightbox.
- `width` and `height` are the original's size in pixels, for the aspect ratio. Either can be `null`.
- Photos come in the order the hotel arranged them in ChannelRUSH. The logo is never among the photos; it is
  `property.logo`.
- A newly uploaded photo appears once ChannelRUSH has processed it, usually within minutes.

## Caching

Each answer carries `Cache-Control: private, max-age=60` and an `ETag`. Send the tag back in `If-None-Match`, and an
unchanged answer is `304 Not Modified` with no body. An edit in ChannelRUSH shows within about a minute.

For a site you build ahead of time, re-fetch on a schedule. With `If-None-Match`, unchanged content costs little.

## Linking to booking

A room page's "Book this room" button links to the page that holds the booking widget, with the room's id:

```html
<a href="/book?crush_rt=1808121">Book this room</a>
```

The widget then lists that room first. Add `crush_rp={ratePlanId}` to pick one of its rate plans, and `crush_ad` /
`crush_dd` (yyyy-MM-dd) to fill in the dates. The ids are the `id`s this API gives for rooms and rate plans. See
[deep links](https://help.channelrush.com/hc/channelrush/articles/booking-widget#deep-links).

## Errors and limits

| Code | HTTP | Meaning |
|---|---|---|
| `key_invalid` | 401 | No key, an unknown or revoked key, or a test key used away from `localhost` |
| `origin_denied` | 403 | A browser call from an address that is not on the key's list |
| `property_disabled` | 403 | The property is switched off, or has no content for the key's languages |
| `not_found` | 404 | The room type, venue, post or page does not exist or is not shown |
| `validation` | 400 | A bad parameter (for example `page=0`) |
| `rate_limited` | 429 | Too many requests: wait the `Retry-After` seconds |

A key gets 600 content requests a minute from one address, and one address gets 1,200 requests a minute in all.
Cache what you fetch, and you will not come near either limit.
