Getting started

The Katanox API lets you search hotel availability, book units and manage those bookings for your customers.

Environments and API keys

There is one base URL for both environments:

https://api.katanox.com/v2

The API key decides the environment:

You find your keys in the Katanox platform under Settings → API keys (app.katanox.com/settings/api-keys). Switch between sandbox and production with the environment selector at the top.

• You can have two keys per environment.
• Rotating a key: create a second key, switch your integration to it, then delete the old one.
• Users with the agent role can't see API keys.

Authentication

Send your key as a bearer token on every request:

curl https://api.katanox.com/v2/properties \
  -H "Authorization: Bearer <YOUR_API_KEY>"

A missing or invalid key returns 401. The full error shape is in Errors.

Rate limits

• Limit: 500 requests per second per API key.

• Above the limit: you get 429 Too Many Requests with this body:

  JSON

  { "error": "request limit reached" }

• Backing off: the window is one second, so wait a short time (with jitter) and retry.

Timeouts

• Server-side limit: each request stops after 15 seconds. Set your client timeout to at least that.
• Bookings: POST /bookings returns as soon as we have accepted the booking. The hotel's confirmation comes later; see Booking.
• Availability: response time depends on the hotel systems behind the properties you search. A slow supplier slows down the whole request. If you need fast, predictable responses, search one property per request and run requests in parallel (Availability).

Responses

Envelope. Successful responses wrap the payload in data. Some responses also include links to related operations:

{
  "data": { "booking": { "...": "..." } },
  "links": {
    "get":    { "method": "GET",    "url": "https://api.katanox.com/v2/bookings/BK-ABCDEFGH" },
    "cancel": { "method": "DELETE", "url": "https://api.katanox.com/v2/bookings/BK-ABCDEFGH" }
  }
}

Empty fields are omitted. Optional fields with no value (for example net_rate, total_tax, vat, breakdown) are left out of the response rather than returned as null. Treat a missing field as "not available", not as an error.

Errors have their own shape; see Errors.

IDs

• Offer IDs are not rate plan IDs. An offer is one specific, priced combination of unit + rate plan + dates + occupancy, and it expires (Offers). The rate plan behind it has its own 8-character rate_plan_id.

Dates, times and currency

• Dates: YYYY-MM-DD, for example check_in=2026-11-02.
• Check-in/check-out times and policy deadlines: these are in the property's local time. Each property exposes its timezone (IANA name, e.g. Europe/Amsterdam).
• Currency: prices are always in the property's currency, given as an ISO 4217 code in every price object. No currency conversion is done, and there is no request parameter to change the currency. See Pricing and taxes.

A typical integration

1. Discover the properties you can sell: GET /properties (contracted properties only). See Properties.
2. Search availability: GET /availability returns offers. See Availability.
3. Re-check the chosen offer just before booking submission: GET /offers/{id}?live_check=true. See Offers.
4. Book: POST /bookings with one reservation per unit, then poll GET /bookings/{id} until each reservation is CONFIRMED or FAILED. See Booking.
5. Manage the booking after it's made:
   • modify a reservation (Reservation)
   • cancel (Cancellation)
   • fetch folios and invoices (Booking → Invoices)

Notifications

There are no webhooks. Booking, modification and cancellation results are only available by polling (Booking).

API versions

Only v2 is supported. Requests to /v1 return 505 HTTP Version Not Supported.