openapi: 3.1.0
info:
  title: Cloudbeds REST API v1.3
  description: |
    Cloudbeds REST API for property management - reservations, guests, rooms,
    rate plans, payments, housekeeping, webhooks, and reporting. v1.3 is the
    current documented version (v1.2 remains available). Authentication is via
    API keys or OAuth 2.0 for technology partners.
  version: "1.3.0"
servers:
  - url: https://hotels.cloudbeds.com/api/v1.3
    description: Cloudbeds REST API v1.3
  - url: https://hotels.cloudbeds.com/api/v1.2
    description: Cloudbeds REST API v1.2 (legacy)
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://hotels.cloudbeds.com/api/v1.2/oauth
          tokenUrl: https://hotels.cloudbeds.com/api/v1.2/access_token
          scopes:
            read: Read access
            write: Write access
  schemas:
    Reservation:
      type: object
      properties:
        reservationID:
          type: string
        guestName:
          type: string
        status:
          type: string
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        roomTypeID:
          type: string
        total:
          type: number
    Guest:
      type: object
      properties:
        guestID:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        phone:
          type: string
    Room:
      type: object
      properties:
        roomID:
          type: string
        roomName:
          type: string
        roomTypeID:
          type: string
    RatePlan:
      type: object
      properties:
        rateID:
          type: string
        roomTypeID:
          type: string
        rate:
          type: number
        date:
          type: string
          format: date
    Payment:
      type: object
      properties:
        paymentID:
          type: string
        reservationID:
          type: string
        amount:
          type: number
        currency:
          type: string
        type:
          type: string
    Webhook:
      type: object
      properties:
        id:
          type: string
        event:
          type: string
        endpointUrl:
          type: string
    SuccessEnvelope:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          type: object
        count:
          type: integer
        total:
          type: integer
security:
  - apiKey: []
  - oauth2: [read, write]
paths:
  /access_token:
    post:
      summary: Obtain OAuth access token
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                client_secret:
                  type: string
                grant_type:
                  type: string
                code:
                  type: string
                redirect_uri:
                  type: string
      responses:
        '200':
          description: Token returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  refresh_token:
                    type: string
                  token_type:
                    type: string
                  expires_in:
                    type: integer
  /userinfo:
    get:
      summary: Get OAuth user info
      responses:
        '200':
          description: User info
          content:
            application/json:
              schema:
                type: object
  /getHotels:
    get:
      summary: List hotels/properties
      responses:
        '200':
          description: Hotels collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getHotelDetails:
    get:
      summary: Get hotel details
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Hotel details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getReservations:
    get:
      summary: List reservations
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
        - name: checkInFrom
          in: query
          schema:
            type: string
            format: date
        - name: checkInTo
          in: query
          schema:
            type: string
            format: date
        - name: pageNumber
          in: query
          schema:
            type: integer
        - name: pageSize
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Reservations list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getReservation:
    get:
      summary: Get reservation
      parameters:
        - name: reservationID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Reservation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reservation'
  /postReservation:
    post:
      summary: Create reservation
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Reservation'
      responses:
        '200':
          description: Reservation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /putReservation:
    put:
      summary: Update reservation
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Reservation'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getGuestList:
    get:
      summary: List guests
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
        - name: pageNumber
          in: query
          schema:
            type: integer
        - name: pageSize
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Guests list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getGuest:
    get:
      summary: Get guest
      parameters:
        - name: guestID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Guest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Guest'
  /postGuest:
    post:
      summary: Create guest
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Guest'
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /putGuest:
    put:
      summary: Update guest
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Guest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getRooms:
    get:
      summary: List rooms
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Rooms
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getRoomTypes:
    get:
      summary: List room types
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Room types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getAvailableRoomTypes:
    get:
      summary: Check available room types
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Availability
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /postRoomAssign:
    post:
      summary: Assign room to reservation
      responses:
        '200':
          description: Assigned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /postRoomCheckIn:
    post:
      summary: Check guest into room
      responses:
        '200':
          description: Checked in
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /postRoomCheckOut:
    post:
      summary: Check guest out of room
      responses:
        '200':
          description: Checked out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getRatePlans:
    get:
      summary: List rate plans
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Rate plans
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getRate:
    get:
      summary: Get rate details
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
        - name: roomTypeID
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Rate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatePlan'
  /putRate:
    put:
      summary: Update rate
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RatePlan'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getPaymentMethods:
    get:
      summary: List payment methods
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Payment methods
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /postPayment:
    post:
      summary: Record a payment
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Payment'
      responses:
        '200':
          description: Payment recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /postCharge:
    post:
      summary: Process a charge
      responses:
        '200':
          description: Charge processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getWebhooks:
    get:
      summary: List webhooks
      parameters:
        - name: propertyID
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Webhooks list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /postWebhook:
    post:
      summary: Create webhook
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Webhook'
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /deleteWebhook:
    delete:
      summary: Delete webhook
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getDashboard:
    get:
      summary: Get dashboard data
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Dashboard
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /getUsers:
    get:
      summary: List users on property
      parameters:
        - name: propertyID
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Users list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'