AegeanBot Reservations API

openapi: 3.2.0
info:
  title: Whitelabel PMS Reservations API
  version: 0.1.0
tags:
- name: Reservations
paths:
  /reservations/{booking_id}/checkin-instructions/preview:
    get:
      summary: Preview Checkin Instructions
      description: '👁 in the console step strip: the exact text the guest would receive.'
      operationId: preview_checkin_instructions_reservations__booking_id__checkin_instructions_preview_get
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Reservations
  /reservations/{booking_id}/checkin-instructions/send:
    post:
      summary: Send Checkin Instructions
      description: 'Console "Send check-in instructions": booking channel first, then the

        send_to_guest fallbacks. 400 when the listing has no check-in info (never

        overridable); 409 {unmet} when the automatic rule isn''t met and force is

        not set, so the console can confirm first.'
      operationId: send_checkin_instructions_reservations__booking_id__checkin_instructions_send_post
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - type: object
                additionalProperties: true
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Reservations
  /reservations/{booking_id}/sync-thread:
    post:
      summary: Reservation Sync Thread
      description: 'Fetch THIS booking''s OTA conversation from Channex right now (thread +

        history). The reservation 💬 calls it when the inbox holds no thread for a

        Channex booking yet — Airbnb creates the thread with the booking, but the

        15-minute account-wide poll lists threads by last message and a fresh,

        message-less thread can sit past its page cap (HMB2Z8YWA4, 2026-09-24).'
      operationId: reservation_sync_thread_reservations__booking_id__sync_thread_post
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Reservations
  /reservations/{booking_id}/ota-message:
    post:
      summary: Reservation Ota Message
      description: 'Owner writes the FIRST message to an OTA guest whose conversation does

        not exist at Channex yet (a Booking.com thread is only created once someone

        writes; Airbnb Instant Book guests who never wrote have none either). Posts

        to the booking — Channex opens the OTA thread — then pulls that thread into

        the inbox so the 💬 opens it (BDC-6691341732, 2026-10-07).'
      operationId: reservation_ota_message_reservations__booking_id__ota_message_post
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - type: object
                additionalProperties: true
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Reservations
  /reservations/{booking_id}/whatsapp-checkin:
    post:
      summary: Send Whatsapp Checkin
      description: 'Ask an unreachable guest to reply, using an approved WATI template.


        A successful send is idempotent. A failed attempt may be retried, and an

        explicit ``force`` is available to an owner who genuinely needs a resend.

        The unique pre-check-in link is released only after the guest replies.'
      operationId: send_whatsapp_checkin_reservations__booking_id__whatsapp_checkin_post
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - type: object
                additionalProperties: true
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Reservations
  /reservations/{booking_id}/collect-balance:
    post:
      summary: Collect Balance
      description: 'PAYMENTS_UI §6.2 (DEP-06): record that the owner collected the deposit-mode

        remaining balance externally (cash/bank/terminal/other). This is NOT a Stripe

        charge and never claims AegeanBot collected the funds; idempotent per booking.'
      operationId: collect_balance_reservations__booking_id__collect_balance_post
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - type: object
                additionalProperties: true
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Reservations
  /reservations/{booking_id}/link-guesty:
    post:
      summary: Reservation Link Guesty
      description: 'Transferred booking: read its payments, schedule and saved card from Guesty (read-only there).'
      operationId: reservation_link_guesty_reservations__booking_id__link_guesty_post
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Reservations
  /reservations/{booking_id}/card:
    get:
      summary: Reservation Card
      description: Masked OTA guest card + what is still owed + which Stripe would be charged.
      operationId: reservation_card_reservations__booking_id__card_get
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Reservations
  /reservations/{booking_id}/charge-card:
    post:
      summary: Reservation Charge Card
      description: Charge the OTA guest's card on the tenant's own Stripe (explicit button).
      operationId: reservation_charge_card_reservations__booking_id__charge_card_post
      parameters:
      - name: booking_id
        in: path
        required: true
        schema:
          type: string
          title: Booking Id
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Reservations
  /reservations/financial-overrides/preview:
    post:
      summary: Preview Financial Overrides
      operationId: preview_financial_overrides_reservations_financial_overrides_preview_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Reservations
  /reservations/financial-overrides:
    put:
      summary: Save Financial Overrides
      operationId: save_financial_overrides_reservations_financial_overrides_put
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Reservations
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError