openapi: 3.1.0
info:
  title: reservations.ai REST API
  description: |
    The REST surface for the reservations.ai travel transaction platform. Provides search, rates, availability, reservation, cancellation, and modification across 1.5 million plus properties in 27 languages. Public read endpoints require no auth. Write endpoints require a Reservation Partner tier bearer token issued via `POST /agents/register`.

    For MCP integration see https://reservations.ai/agents.md. For the full capability manifest see https://reservations.ai/manifest.json.
  version: "2.5.0"
  contact:
    name: Developers
    email: developers@reservations.ai
    url: https://reservations.ai/developers.html
  license:
    name: Proprietary
servers:
  - url: https://api.reservations.com
    description: Production
  - url: https://sandbox.reservations.com
    description: Sandbox
security:
  - bearerAuth: []
paths:
  /v1/properties/search:
    get:
      summary: Search properties
      description: Query inventory by destination, dates, guest count, and filters.
      security: []
      parameters:
        - in: query
          name: destination
          required: true
          schema: { type: string }
        - in: query
          name: check_in
          required: true
          schema: { type: string, format: date }
        - in: query
          name: check_out
          required: true
          schema: { type: string, format: date }
        - in: query
          name: adults
          required: true
          schema: { type: integer, minimum: 1 }
        - in: query
          name: children
          schema: { type: integer, minimum: 0, default: 0 }
        - in: query
          name: currency
          schema: { type: string, default: USD }
      responses:
        "200":
          description: A list of matching properties
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PropertyList"
  /v1/properties/{property_id}/rates:
    get:
      summary: Get live rates for a property
      security: []
      parameters:
        - in: path
          name: property_id
          required: true
          schema: { type: string }
        - in: query
          name: check_in
          required: true
          schema: { type: string, format: date }
        - in: query
          name: check_out
          required: true
          schema: { type: string, format: date }
        - in: query
          name: adults
          required: true
          schema: { type: integer, minimum: 1 }
        - in: query
          name: currency
          schema: { type: string, default: USD }
      responses:
        "200":
          description: Rate list with taxes and fees
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RateList"
  /v1/availability:
    post:
      summary: Real time availability check with optional soft hold
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [property_id, rate_id, check_in, check_out]
              properties:
                property_id: { type: string }
                rate_id: { type: string }
                check_in: { type: string, format: date }
                check_out: { type: string, format: date }
                soft_hold: { type: boolean, default: false }
      responses:
        "200":
          description: Availability and optional hold token
          content:
            application/json:
              schema:
                type: object
                properties:
                  available: { type: boolean }
                  hold_token: { type: string, nullable: true }
                  hold_expires_at: { type: string, format: date-time, nullable: true }
  /v1/reservations:
    post:
      summary: Create a reservation intent (phase 1 of two phase commit)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [rate_id, guests, payment_token, contact]
              properties:
                rate_id: { type: string }
                guests:
                  type: array
                  items: { $ref: "#/components/schemas/Guest" }
                payment_token: { type: string }
                contact: { $ref: "#/components/schemas/Contact" }
      responses:
        "200":
          description: Reservation intent created
          content:
            application/json:
              schema:
                type: object
                properties:
                  booking_intent_id: { type: string }
                  expires_at: { type: string, format: date-time }
                  total_usd: { type: number }
  /v1/reservations/{booking_intent_id}/confirm:
    post:
      summary: Confirm reservation (phase 2 of two phase commit)
      parameters:
        - in: path
          name: booking_intent_id
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Reservation confirmed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Booking"
  /v1/reservations/{confirmation_number}:
    get:
      summary: Retrieve a reservation
      parameters:
        - in: path
          name: confirmation_number
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Reservation record
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Booking"
    delete:
      summary: Cancel a reservation
      parameters:
        - in: path
          name: confirmation_number
          required: true
          schema: { type: string }
        - in: query
          name: reason
          schema: { type: string }
      responses:
        "200":
          description: Cancellation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  cancelled: { type: boolean }
                  refund_usd: { type: number }
    patch:
      summary: Modify a reservation
      parameters:
        - in: path
          name: confirmation_number
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                check_in: { type: string, format: date }
                check_out: { type: string, format: date }
                guests:
                  type: array
                  items: { $ref: "#/components/schemas/Guest" }
      responses:
        "200":
          description: Updated reservation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Booking"
  /v1/agents/register:
    post:
      summary: Register an autonomous agent
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [agent_id, principal, pre_auth]
              properties:
                agent_id: { type: string }
                principal: { type: string }
                pre_auth:
                  type: object
                  required: [max_usd, scope, expires_at]
                  properties:
                    max_usd: { type: number }
                    scope:
                      type: array
                      items: { type: string, enum: [hotel, car, activity, flight] }
                    expires_at: { type: string, format: date-time }
                aec_pool: { type: number, minimum: 500 }
      responses:
        "200":
          description: Agent registered
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent_token: { type: string }
                  aec_balance: { type: number }
                  rate_limit:
                    type: object
                    properties:
                      rpm: { type: integer }
                  manifest_url: { type: string }
                  status: { type: string, enum: [active, pending, revoked] }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    PropertyList:
      type: object
      properties:
        currency: { type: string }
        results:
          type: array
          items: { $ref: "#/components/schemas/Property" }
    Property:
      type: object
      properties:
        property_id: { type: string }
        name: { type: string }
        address: { type: string }
        rating: { type: number }
        thumbnail: { type: string, format: uri }
        from_price: { type: number }
    RateList:
      type: object
      properties:
        currency: { type: string }
        rates:
          type: array
          items: { $ref: "#/components/schemas/Rate" }
    Rate:
      type: object
      properties:
        rate_id: { type: string }
        room_type: { type: string }
        bed_type: { type: string }
        cancellable: { type: boolean }
        nightly_rate: { type: number }
        taxes_total: { type: number }
        fees_total: { type: number }
        total: { type: number }
    Guest:
      type: object
      properties:
        first_name: { type: string }
        last_name: { type: string }
        age: { type: integer }
    Contact:
      type: object
      properties:
        email: { type: string, format: email }
        phone: { type: string }
    Booking:
      type: object
      properties:
        confirmation_number: { type: string }
        property_id: { type: string }
        rate_id: { type: string }
        check_in: { type: string, format: date }
        check_out: { type: string, format: date }
        guests:
          type: array
          items: { $ref: "#/components/schemas/Guest" }
        total_usd: { type: number }
        status: { type: string, enum: [pending, confirmed, cancelled, completed] }