ATAbooking

Find hotels with a room free for the dates and guests. Returns each stay's cheapest fitting room with a quote (price, ATA fee 5%, typical 15-20% OTA cut). Demo hotels are marked demo: true. Results come in pages: when more_results is true, call search_stays again with the same arguments plus cursor: next_cursor to get the rest. Nothing is left out.

{
  "type": "object",
  "properties": {
    "place": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "City, area, country or hotel name, e.g. 'Bangkok' or 'Gamla Stan'"
    },
    "check_in": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Arrival date, YYYY-MM-DD"
    },
    "check_out": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Departure date, YYYY-MM-DD"
    },
    "guests": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Number of guests in one room"
    },
    "max_price_per_night": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1000000,
      "description": "Budget per night in the hotel's currency (EUR in the demo)"
    },
    "wants": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 80
      },
      "maxItems": 20,
      "description": "Nice-to-haves, e.g. ['pool','beach','quiet']; ranks matches first"
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 400,
      "description": "next_cursor from the previous page of this same search, to get the next page"
    }
  },
  "required": [
    "place",
    "check_in",
    "check_out",
    "guests"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Rooms, prices, what's included, check-in/out times and cancellation terms for one stay. Demo hotels are marked demo: true.

{
  "type": "object",
  "properties": {
    "stay_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "pattern": "^[a-zA-Z0-9_-]+$",
      "description": "stay_id from search_stays"
    },
    "check_in": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Optional: with check_out, adds availability and a quote per room"
    },
    "check_out": {
      "$ref": "#/properties/check_in"
    },
    "guests": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    }
  },
  "required": [
    "stay_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Re-check one room for exact dates and guests right before booking. Returns available yes/no and the live quote. Demo hotels are marked demo: true.

{
  "type": "object",
  "properties": {
    "stay_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "pattern": "^[a-zA-Z0-9_-]+$"
    },
    "room_id": {
      "$ref": "#/properties/stay_id"
    },
    "check_in": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "check_out": {
      "$ref": "#/properties/check_in"
    },
    "guests": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    }
  },
  "required": [
    "stay_id",
    "room_id",
    "check_in",
    "check_out",
    "guests"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Places a 15-minute HOLD on the room and emails the guest a 6-digit code. Nothing is booked and nothing reaches the hotel until the guest confirms. After calling, tell the guest: check your email (the result shows the masked address), then either read the code back to you (call confirm_booking) or click Confirm in the email. Send an idempotency_key and reuse it if you retry. Confirm name, email, dates and price with the guest before calling. Demo hotels (demo: true) confirm at once and send no email.

{
  "type": "object",
  "properties": {
    "stay_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "pattern": "^[a-zA-Z0-9_-]+$"
    },
    "room_id": {
      "$ref": "#/properties/stay_id"
    },
    "check_in": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "check_out": {
      "$ref": "#/properties/check_in"
    },
    "guests": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    },
    "guest_name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 120
    },
    "guest_email": {
      "type": "string",
      "maxLength": 254,
      "format": "email"
    },
    "guest_phone": {
      "type": "string",
      "maxLength": 40
    },
    "notes": {
      "type": "string",
      "maxLength": 1000,
      "description": "Requests for the hotel, e.g. late arrival"
    },
    "agent": {
      "type": "string",
      "maxLength": 120,
      "description": "Name of the AI agent/app placing the request"
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9_-]+$",
      "description": "One per booking attempt (8-128 of A-Z a-z 0-9 _ -). Reuse it on retries to get the same hold back."
    }
  },
  "required": [
    "stay_id",
    "room_id",
    "check_in",
    "check_out",
    "guests",
    "guest_name",
    "guest_email"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Confirm a held booking with the 6-digit code the guest received by email. Only use a code the guest gave you. Five wrong codes cancel the hold. Confirming twice returns the same booking.

{
  "type": "object",
  "properties": {
    "hold_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40,
      "description": "hold_id from book_direct"
    },
    "code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "description": "The 6-digit code from the guest's email"
    }
  },
  "required": [
    "hold_id",
    "code"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}