{
  "openapi": "3.1.0",
  "info": {
    "title": "L'Argamak Hotel Booking API",
    "version": "1.1.0",
    "summary": "Official real-time hotel availability and direct pricing API for L'Argamak Hotel in Samarkand.",
    "description": "Official public API operated by L'Argamak Hotel. It exposes hotel facts, room types, live WuBook availability, official direct price quotes and reservation initiation. Automated agents should prefer POST /v1/quotes, then POST /v1/reservation-intents after the guest chooses a package. Prices, promotions and tourist taxes are dynamic; use live responses and never infer an official total from cached content. Reservation initiation returns a secure L'Argamak guest-completion URL. Guest completion immediately triggers email/PDF/manage access; PMS synchronization is a separate internal workflow. The public API never creates reservations directly in WuBook.",
    "contact": {
      "name": "L'Argamak Hotel",
      "email": "contact@largamak.com",
      "url": "https://www.largamak.com/en/contact-us"
    }
  },
  "servers": [
    {
      "url": "https://api.largamak.com",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Human-readable API documentation",
    "url": "https://api.largamak.com/docs/"
  },
  "tags": [
    {
      "name": "Discovery",
      "description": "API discovery and health."
    },
    {
      "name": "Hotel",
      "description": "Official hotel and room metadata."
    },
    {
      "name": "Availability",
      "description": "Real-time WuBook inventory."
    },
    {
      "name": "Quotes",
      "description": "Official live direct price quotes."
    }
  ],
  "x-ai-agent-guidance": [
    "Prefer POST /v1/quotes for quoting one or multiple rooms.",
    "Never calculate, infer or cache an official total independently of a live quote.",
    "Maximum standard occupancy is 2 guests per room.",
    "One infant under 2 may be added; baby cot is free and on request.",
    "Check-in 14:00 and check-out 12:00 are strict.",
    "Tourist tax is dynamic by stay date and guest age and is returned by the quote engine.",
    "Do not present reservation creation as available until a future booking endpoint is published."
  ],
  "paths": {
    "/": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getApiRoot",
        "summary": "Discover the official API",
        "responses": {
          "200": {
            "description": "API discovery document"
          }
        }
      }
    },
    "/v1": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getApiIndex",
        "summary": "List public API capabilities",
        "responses": {
          "200": {
            "description": "Machine-readable public API index"
          }
        }
      }
    },
    "/v1/health": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getHealth",
        "summary": "Check API status",
        "responses": {
          "200": {
            "description": "API is online"
          }
        }
      }
    },
    "/v1/hotel": {
      "get": {
        "tags": [
          "Hotel"
        ],
        "operationId": "getHotel",
        "summary": "Get official hotel facts and policies",
        "responses": {
          "200": {
            "description": "Hotel metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Hotel"
                }
              }
            }
          }
        }
      }
    },
    "/v1/room-types": {
      "get": {
        "tags": [
          "Hotel"
        ],
        "operationId": "getRoomTypes",
        "summary": "List room types and occupancy rules",
        "responses": {
          "200": {
            "description": "Room type catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "rooms": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RoomType"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/availability": {
      "get": {
        "tags": [
          "Availability"
        ],
        "operationId": "searchAvailability",
        "summary": "Search live availability for a stay",
        "description": "Reads live room inventory from WuBook. For price and policy evaluation, use POST /v1/quotes.",
        "parameters": [
          {
            "name": "checkin",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "checkout",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "adults",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2,
              "default": 2
            }
          },
          {
            "name": "children",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Live availability result"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/v1/quote": {
      "post": {
        "tags": [
          "Quotes"
        ],
        "operationId": "quoteSingleRoom",
        "summary": "Create an official live quote for one room",
        "description": "Supported single-room quote endpoint. Agents should prefer /v1/quotes for a consistent one- or multi-room workflow.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SingleRoomQuoteRequest"
              },
              "examples": {
                "twoAdults": {
                  "value": {
                    "checkin": "2026-10-20",
                    "checkout": "2026-10-23",
                    "adults": 2,
                    "children": 0,
                    "room_type_id": "double"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Official live quote"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/v1/quotes": {
      "post": {
        "tags": [
          "Quotes"
        ],
        "operationId": "quoteRooms",
        "summary": "Create an official one- or multi-room live quote",
        "description": "Recommended quote endpoint for automated agents. It validates aggregate inventory, occupancy, rate eligibility, promotions and tourist tax. It returns package_offers with totals for all requested rooms so clients do not need to add room totals themselves.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MultiRoomQuoteRequest"
              },
              "examples": {
                "familyTwoRooms": {
                  "summary": "Two rooms, including a free baby cot request",
                  "value": {
                    "session_id": "agent-session-123",
                    "checkin": "2026-10-20",
                    "checkout": "2026-10-23",
                    "rooms": [
                      {
                        "room_type_id": "double",
                        "quantity": 1,
                        "adults": 2,
                        "children_ages": [
                          1
                        ]
                      },
                      {
                        "room_type_id": "twin",
                        "quantity": 1,
                        "adults": 1,
                        "children_ages": [
                          10
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Official live multi-room quote",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MultiRoomQuoteResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/v1/reservation-intents": {
      "post": {
        "tags": [
          "Quotes"
        ],
        "operationId": "createReservationIntent",
        "summary": "Create a pending reservation and secure guest completion link",
        "description": "Creates a L'Argamak reservation record from a still-valid production quote. It does not write to WuBook or KWHotel. The guest must open continue_url and complete required information.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 160
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "quote_id",
                  "package_code"
                ],
                "properties": {
                  "quote_id": {
                    "type": "string"
                  },
                  "package_code": {
                    "type": "string"
                  },
                  "language": {
                    "type": "string",
                    "enum": [
                      "en",
                      "fr",
                      "ru"
                    ],
                    "default": "en"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reservation intent created; present continue_url to the user."
          },
          "409": {
            "description": "Quote expired or no longer reservable."
          }
        }
      }
    },
    "/v1/reservation-public": {
      "get": {
        "tags": [
          "Quotes"
        ],
        "operationId": "getPendingReservation",
        "summary": "Read a pending reservation via secure token",
        "parameters": [
          {
            "name": "X-Reservation-Token",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Secure bearer token used by the official L'Argamak guest portal."
          }
        ],
        "responses": {
          "200": {
            "description": "Prefilled reservation data and configured guest fields"
          }
        }
      }
    },
    "/v1/reservation-complete": {
      "post": {
        "tags": [
          "Quotes"
        ],
        "operationId": "completeReservationGuestData",
        "summary": "Complete required guest data and issue email, PDF and management link",
        "description": "Revalidates live availability and price. On success status becomes GUEST_COMPLETED and PMS status becomes PENDING. No payment is required in v12.",
        "responses": {
          "200": {
            "description": "Guest completion successful"
          },
          "409": {
            "description": "Availability or price changed"
          }
        }
      }
    },
    "/v1/reservation-manage": {
      "get": {
        "tags": [
          "Quotes"
        ],
        "operationId": "getManagedReservation",
        "summary": "Read a completed reservation through the secure management token",
        "parameters": [
          {
            "name": "X-Reservation-Token",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Reservation management view"
          }
        }
      },
      "post": {
        "tags": [
          "Quotes"
        ],
        "operationId": "manageReservation",
        "summary": "Update allowed guest details or request an allowed cancellation",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Management action completed"
          }
        }
      }
    },
    "/v1/reservation-document": {
      "get": {
        "tags": [
          "Quotes"
        ],
        "operationId": "downloadReservationPdf",
        "summary": "Download the confirmation PDF using the secure management token",
        "parameters": [
          {
            "name": "X-Reservation-Token",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "PDF confirmation",
            "content": {
              "application/pdf": {}
            }
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "BadRequest": {
        "description": "Invalid request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "Hotel": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "largamak"
          },
          "name": {
            "type": "string",
            "example": "L'Argamak Hotel"
          },
          "city": {
            "type": "string",
            "example": "Samarkand"
          },
          "country": {
            "type": "string",
            "example": "Uzbekistan"
          },
          "check_in": {
            "type": "string",
            "example": "14:00"
          },
          "check_out": {
            "type": "string",
            "example": "12:00"
          },
          "tourist_tax": {
            "type": "object",
            "description": "Dynamic; official amount is calculated in live quote responses."
          }
        }
      },
      "RoomType": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "double",
              "twin",
              "deluxe"
            ]
          },
          "name": {
            "type": "string"
          },
          "size_m2": {
            "type": "number"
          },
          "max_standard_occupancy": {
            "type": "integer",
            "const": 2
          },
          "additional_infant_under_2_allowed": {
            "type": "boolean",
            "const": true
          },
          "max_additional_infants_under_2": {
            "type": "integer",
            "const": 1
          },
          "baby_cot": {
            "type": "object",
            "properties": {
              "available": {
                "type": "boolean"
              },
              "on_request": {
                "type": "boolean"
              },
              "price": {
                "type": "number"
              },
              "currency": {
                "type": "string"
              }
            }
          }
        }
      },
      "SingleRoomQuoteRequest": {
        "type": "object",
        "required": [
          "checkin",
          "checkout",
          "adults",
          "children",
          "room_type_id"
        ],
        "properties": {
          "checkin": {
            "type": "string",
            "format": "date"
          },
          "checkout": {
            "type": "string",
            "format": "date"
          },
          "adults": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2
          },
          "children": {
            "type": "integer",
            "minimum": 0
          },
          "children_ages": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 0,
              "maximum": 17
            },
            "description": "Required when children > 0."
          },
          "room_type_id": {
            "type": "string",
            "enum": [
              "double",
              "twin",
              "deluxe"
            ]
          },
          "rate_code": {
            "type": "string",
            "description": "Optional. Omit to return all eligible active rate plans."
          }
        }
      },
      "RoomRequest": {
        "type": "object",
        "required": [
          "room_type_id",
          "adults"
        ],
        "properties": {
          "room_type_id": {
            "type": "string",
            "enum": [
              "double",
              "twin",
              "deluxe"
            ]
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 1
          },
          "adults": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2
          },
          "children_ages": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 0,
              "maximum": 17
            },
            "description": "Children assigned to this room. Standard occupancy is 2. One infant under 2 may be added beyond standard occupancy; baby cot is free on request."
          },
          "rate_code": {
            "type": "string",
            "description": "Optional specific rate code."
          }
        }
      },
      "MultiRoomQuoteRequest": {
        "type": "object",
        "required": [
          "checkin",
          "checkout",
          "rooms"
        ],
        "properties": {
          "session_id": {
            "type": "string",
            "maxLength": 80,
            "description": "Optional correlation ID supplied by the calling agent."
          },
          "checkin": {
            "type": "string",
            "format": "date"
          },
          "checkout": {
            "type": "string",
            "format": "date"
          },
          "rooms": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/RoomRequest"
            }
          }
        }
      },
      "PackageOffer": {
        "type": "object",
        "properties": {
          "package_code": {
            "type": "string"
          },
          "rate_code": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "breakfast_included": {
            "type": "boolean"
          },
          "refundable": {
            "type": "boolean"
          },
          "promotions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "price": {
            "type": "object",
            "properties": {
              "room_total": {
                "type": "number"
              },
              "promotion_discount": {
                "type": "number"
              },
              "tourist_tax": {
                "type": "number"
              },
              "total": {
                "type": "number"
              },
              "currency": {
                "type": "string",
                "example": "EUR"
              }
            }
          }
        }
      },
      "MultiRoomQuoteResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "available"
          },
          "environment": {
            "type": "string",
            "example": "production"
          },
          "quote_id": {
            "type": "string"
          },
          "session_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "stay": {
            "type": "object",
            "properties": {
              "checkin": {
                "type": "string",
                "format": "date"
              },
              "checkout": {
                "type": "string",
                "format": "date"
              },
              "nights": {
                "type": "integer"
              },
              "check_in_time": {
                "type": "string",
                "example": "14:00"
              },
              "check_out_time": {
                "type": "string",
                "example": "12:00"
              }
            }
          },
          "package_offers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PackageOffer"
            },
            "description": "Globally priced packages for all requested rooms. Prefer these totals."
          }
        }
      }
    }
  }
}