Worlds / Travel

Booking.com API

A local Booking.com extranet with properties, room types, rates, availability and reservations with cancellation policies. Test the hotel agent that handles modifications, cancellations and no shows.

Base path: /json
Auth: HTTP basic with machine account, or bearer token, the world key
Endpoints: 13
Status: Active today

This reference previews the surface the Booking.com world serves in the closed beta. Paths mirror the public Booking.com API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_BOOKING_COM_URL`	This world's origin followed by `/json`
`WORLDS_API_KEY`	The world key, accepted wherever Booking.com expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

const base = process.env.WORLDS_BOOKING_COM_URL + "/json";

const res = await fetch(base + "/bookingDetails?hotel_ids=10001&last_change=2026-10-01", {
  headers: {
    Authorization: "Bearer " + process.env.WORLDS_API_KEY,
    Accept: "application/json",
  },
});

const data = await res.json();
console.log(data.result.length);

API reference

13 of 13

Reservations

Guest bookings made through the channel.

GET/json/bookingDetailsList reservations
GET/json/bookingDetails/{reservation_id}Get a reservation
POST/json/reservationsConfirmConfirm received reservations
POST/json/cancelReservationCancel a reservation

Fields · 6

`id`	string	Reservation id
`hotel_id`	integer	Property id
`status`	string	new, modified, cancelled
`arrival_date`	date	Check-in
`departure_date`	date	Check-out
`totalprice`	number	Total price

Properties

Hotels the account manages.

GET/json/hotelsList properties
GET/json/hotels/{hotel_id}Get a property
PUT/json/hotels/{hotel_id}Update property details

Fields · 5

`hotel_id`	integer	Property id
`name`	string	Property name
`city`	string	City
`currency`	string	Contract currency
`checkin_from`	string	Earliest check-in time

Rooms and rates

Room types and rate plans.

GET/json/hotels/{hotel_id}/roomsList room types
GET/json/hotels/{hotel_id}/ratesList rate plans

Fields · 5

`room_id`	integer	Room type id
`room_name`	string	Room name
`rate_id`	integer	Rate plan id
`max_persons`	integer	Max guests
`meal_plan`	string	Meal plan code

Availability

Inventory and price per day.

GET/json/availabilityGet availability and rates
POST/json/availabilityUpdate availability and rates

Fields · 6

`room_id`	integer	Room type id
`rate_id`	integer	Rate plan id
`date`	date	Stay date
`rooms_to_sell`	integer	Units open
`price`	number	Nightly rate
`closed`	boolean	Closed to sale

Guest reviews

Review scores and text.

GET/json/reviewsList reviews
POST/json/reviews/{review_id}/replyReply to a review

Fields · 5

`review_id`	string	Review id
`score`	number	Score out of 10
`headline`	string	Review title
`reviewer`	object	Guest name and country
`reply`	string	Property reply

Test workflow

Prepare. Select the Booking.com setup for your workflow and review its starting records, including reservations, properties, rooms and rates.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

Test, B canceled with no fee
Demo, C still booked, fee policy unchanged
Example, D moved to Thursday with a room available
No reservation marked no show before its arrival date
Thursday availability never goes below zero

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Booking.com
version: 2
connector: booking-com
seed: booking-com-starter
mode: isolated
policy: >
  Handle this week's guest requests. Cancel free cancellation bookings at no
  charge, charge the full stay on non refundable ones, and move date changes
  only to nights with rooms left.
tasks:
  - id: process-guest-cancellations-under-the-right-policy
    prompt: Process guest cancellations under the right policy
  - id: mark-no-shows-after-the-arrival-date
    prompt: Mark no shows after the arrival date
  - id: update-availability-and-rates-for-the-next-30-days
    prompt: Update availability and rates for the next 30 days
expected:
  - "Test, B canceled with no fee"
  - "Demo, C still booked, fee policy unchanged"
  - "Example, D moved to Thursday with a room available"
  - No reservation marked no show before its arrival date
  - Thursday availability never goes below zero
scenarios:
  - unacknowledged-reservation
  - rate-limited
  - modification-lands

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`unacknowledged-reservation`	A new reservation is delivered again until it is acknowledged
`rate-limited`	Availability pushes return 429
`modification-lands`	The guest modifies the booking during the agent's update
`overbooked-night`	Availability for Thursday is already zero

Starting data

Start each run from the same records and relationships. The overview below describes the Booking.com starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
properties	2 hotels with 8 room types
reservations	80 across new, modified and cancelled
rate plans	Standard, non refundable and breakfast included
cancellation policies	Free until 48 hours before arrival, or non refundable
availability	Rooms to sell for 90 days, two nights overbooked

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Reservations records

Reservations

Guest bookings made through the channel.

Field	Type	Meaning / relationship
`id`	string	Reservation id
`hotel_id`	integer	Property id
`status`	string	new, modified, cancelled
`arrival_date`	date	Check-in
`departure_date`	date	Check-out
`totalprice`	number	Total price

json · illustrative record shape

{
  "id": "<Reservation id>",
  "hotel_id": 1,
  "status": "<new, modified, cancelled>",
  "arrival_date": "<Check-in>",
  "departure_date": "<Check-out>",
  "totalprice": 1
}

See reservations operations

Properties records

Properties

Hotels the account manages.

Field	Type	Meaning / relationship
`hotel_id`	integer	Property id
`name`	string	Property name
`city`	string	City
`currency`	string	Contract currency
`checkin_from`	string	Earliest check-in time

json · illustrative record shape

{
  "hotel_id": 1,
  "name": "<Property name>",
  "city": "<City>",
  "currency": "<Contract currency>",
  "checkin_from": "<Earliest check-in time>"
}

See properties operations

Rooms and rates records

Rooms and rates

Room types and rate plans.

Field	Type	Meaning / relationship
`room_id`	integer	Room type id
`room_name`	string	Room name
`rate_id`	integer	Rate plan id
`max_persons`	integer	Max guests
`meal_plan`	string	Meal plan code

json · illustrative record shape

{
  "room_id": 1,
  "room_name": "<Room name>",
  "rate_id": 1,
  "max_persons": 1,
  "meal_plan": "<Meal plan code>"
}

See rooms and rates operations

Availability records

Availability

Inventory and price per day.

Field	Type	Meaning / relationship
`room_id`	integer	Room type id
`rate_id`	integer	Rate plan id
`date`	date	Stay date
`rooms_to_sell`	integer	Units open
`price`	number	Nightly rate
`closed`	boolean	Closed to sale

json · illustrative record shape

{
  "room_id": 1,
  "rate_id": 1,
  "date": "<Stay date>",
  "rooms_to_sell": 1,
  "price": 1,
  "closed": false
}

See availability operations

Guest reviews records

Guest reviews

Review scores and text.

Field	Type	Meaning / relationship
`review_id`	string	Review id
`score`	number	Score out of 10
`headline`	string	Review title
`reviewer`	object	Guest name and country
`reply`	string	Property reply

json · illustrative record shape

{
  "review_id": "<Review id>",
  "score": 1,
  "headline": "<Review title>",
  "reviewer": {},
  "reply": "<Property reply>"
}

See guest reviews operations

See the Booking.com world in the catalog