> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gridbeds.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Distribution API

> Read the properties, prices and availability that hosts on Gridbeds publish to your listing site, and be told when they change.

<Warning>
  **Preview: nothing is served yet.** The Distribution API is a released contract (version `1.0.0`), and every operation in it is planned, not live yet. Build against a mock of the contract today ([Testing](/en/distribution-api/testing)); the sandbox opens with the first test key. Send comments on any part of it to [support@gridbeds.com](mailto:support@gridbeds.com).
</Warning>

The Gridbeds Distribution API is for listing sites and other distribution channels. It gives your channel the locations, owners and properties that hosts on Gridbeds choose to publish to you, with each property's nightly availability, prices and restrictions, and it tells you when any of them changes.

## Pull for data, push for notifications

You read everything with `GET` requests. A webhook only says that something changed and names it: read the resource it names to see what changed. You can also read the same notifications as an ordered log, `GET /events`, which is how you catch up after any gap.

| Resource | What it is |
| - | - |
| **Location** | A building or address where published properties are: address, coordinates, time zone, photos. |
| **Owner** | Who offers the properties: a company or an individual, with a display name and, for a company, its legal details. |
| **Property** | One listing per room type: its units, capacity, photos, rate plans, fees, check-in and check-out times, house rules and the legal data its country asks for. |
| **Availability** | Per property and night: units available, minimum and maximum stay, arrival and departure closures, and a price per rate plan. |
| **Amenity** | The catalogue of amenity codes properties use, with their OpenTravel codes. |
| **Event** | One entry of the log of what changed, the same thing a webhook delivers. |

`GET /channel` describes the channel your key belongs to: its environment, the scopes the key holds, your rate limit and how many properties are distributed to you. Any key can call it.

## Environments

| Environment | Base URL | Keys |
| - | - | - |
| Production | `https://api.gridbeds.com/api/v1/distribution` | `gbd_live_…` |
| Sandbox | `https://staging-api.gridbeds.com/api/v1/distribution` | `gbd_test_…` |

Only HTTPS is accepted, with TLS 1.2 or later. A plain-HTTP request is refused, never redirected, because its key has already crossed the network in clear: treat such a key as compromised and roll it.

## Conventions

* **Ids** are opaque strings with a prefix (`loc_`, `own_`, `prp_`, `rpl_`, `pho_`, `whk_`, `dlv_`, `evt_`), specific to your channel and never reused. Do not parse them.
* **Instants** are RFC 3339 in UTC, to the second, ending in `Z`: `2026-10-16T09:30:00Z`.
* **Nights** are dates in the property's own time zone (`timezone`).
* **Money** is `{"amount": 45000, "currency": "RON"}`: an integer in ISO 4217 minor units, so 45000 RON is 450.00 lei.
* **Text** is a map from a BCP 47 language to plain text, and always contains the property's source language: `ro` for a property in Romania. It holds no HTML, links, e-mail addresses or phone numbers.
* **Every enum is open**: accept values you do not know.

## Versions

Version 1 only grows: new fields, new values in an enum, new event types and new legal identifier schemes arrive without a new version. A breaking change is a new version, `/v2`, announced at least 30 days ahead with `Deprecation` and `Sunset` headers.

## Read on

<CardGroup cols={2}>
  <Card title="Authentication" icon="key-round" href="/en/distribution-api/authentication">
    Keys, scopes and rotation.
  </Card>

  <Card title="Synchronisation" icon="refresh-cw" href="/en/distribution-api/synchronisation">
    Lists, `updated_since`, versions and tombstones.
  </Card>

  <Card title="Legal data" icon="scale" href="/en/distribution-api/legal-data">
    What each country's law asks a listing to show.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/en/distribution-api/webhooks">
    Verifying a signature, retries and suspension.
  </Card>

  <Card title="Errors and rate limits" icon="triangle-alert" href="/en/distribution-api/errors-and-limits">
    Problem details and the `RateLimit` headers.
  </Card>

  <Card title="Testing" icon="flask-conical" href="/en/distribution-api/testing">
    A mock of the contract today, the sandbox next.
  </Card>
</CardGroup>

Every page under **Reference** is generated from the contract, the OpenAPI document this API will be built and checked against. The reference pages are in English, like the document.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.