AegeanBot Brains API

openapi: 3.2.0
info:
  title: Whitelabel PMS Brains API
  version: 0.1.0
tags:
- name: Brains
paths:
  /brains/precheckin-docs-purge:
    post:
      summary: Precheckin Docs Purge
      description: 'Scheduler (daily): delete identity documents past the retention window.'
      operationId: precheckin_docs_purge_brains_precheckin_docs_purge_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Brains
  /brains/route:
    post:
      summary: Brains Route
      description: 'THE W2 router: every channel adapter posts inbound messages here.

        {channel, sender_email, text, subject?, sender_phone?, thread_ref?} →

        identity → brain → threads/messages log → {kind, reply|null}. Unknown

        senders get an escalation + owner task and NO auto-reply.

        Plain `def`: the brain calls the sync OpenAI client (seconds to 30 s+) —

        as `async def` that ran on the event loop and stalled every request.'
      operationId: brains_route_brains_route_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brains
  /brains/copilot:
    post:
      summary: Brains Copilot
      description: 'Headless copilot for trusted front-ends (§3b owner branch of the bot''s

        /copilot entry). The CALLER verifies the owner''s Clerk JWT; transport trust

        is the dispatch secret. Same tools + RLS + copilot_audit as the widget.

        Plain `def` (threadpool) — the 8-round tool loop is sync LLM I/O.'
      operationId: brains_copilot_brains_copilot_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brains
  /brains/guest-auth:
    post:
      summary: Brains Guest Auth
      description: 'Reservation two-factor for channel adapters + the web-chat starter (§1):

        {email, ref_or_phone, owner_id?} → {authenticated, summary?}. Auth state is

        code-enforced here, never in a prompt.'
      operationId: brains_guest_auth_brains_guest_auth_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Brains
  /brains/stay/state:
    post:
      summary: Stay State
      operationId: stay_state_brains_stay_state_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brains
  /brains/stay/precheckin-update:
    post:
      summary: Stay Precheckin Update
      operationId: stay_precheckin_update_brains_stay_precheckin_update_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brains
  /brains/stay/arrival-pack:
    post:
      summary: Stay Arrival Pack
      description: 'THE server-side secrets gate (§7): locked responses carry reasons only,

        never the fields. The model cannot fetch secrets any other way.'
      operationId: stay_arrival_pack_brains_stay_arrival_pack_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brains
  /brains/scheduled-replies-drain:
    post:
      summary: Scheduled Replies Drain
      description: 'Scheduler (*/5 min): deliver due ''Send later'' replies. Same guard as the

        other drains.'
      operationId: scheduled_replies_drain_brains_scheduled_replies_drain_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Brains
  /brains/wati-sync:
    post:
      summary: Wati Sync
      description: 'Scheduler (*/5 min): WATI history safety net for active WhatsApp threads

        (see wati_whatsapp.sync_recent_threads). Same guard as the other drains.'
      operationId: wati_sync_brains_wati_sync_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Brains
  /brains/inquiry-sync:
    post:
      summary: Inquiry Sync
      description: 'Admin: (back)fill Airbnb inquiry dates from the Channex live feed.'
      operationId: inquiry_sync_brains_inquiry_sync_post
      parameters:
      - name: pages
        in: query
        required: false
        schema:
          type: integer
          default: 2
          title: Pages
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brains
  /brains/faq-retrieve:
    post:
      summary: Faq Retrieve
      description: 'Semantic retrieval over knowledge_entries (Gemini 768 space — global

        decision #2: ONE space, embedded and queried PMS-side). Server-to-server.'
      operationId: faq_retrieve_brains_faq_retrieve_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brains
  /brains/qa-mining/load:
    post:
      summary: Qa Mining Load
      description: 'GUESTY_QA_MINING Stage 6: the bot-side loader posts guesty_qa.canonical

        rows here; they land as DRAFTS / staff suggestions (app/mined_knowledge.py).

        Nothing becomes guest-visible until approved (status=''active'').'
      operationId: qa_mining_load_brains_qa_mining_load_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brains
  /brains/suggest-drain:
    post:
      summary: Suggest Drain Scheduled
      description: 'Scheduler (*/2 min): generate inbox AI suggestions for queued guest

        messages (90s debounce inside). Same guard as the other drains.'
      operationId: suggest_drain_scheduled_brains_suggest_drain_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Brains
  /brains/repair-scan:
    post:
      summary: Repair Scan Scheduled
      description: 'Daily safety net for old messages and any suggestion runs missed during

        an outage. Every message is reviewed at most once unless its ledger is

        deliberately cleared.'
      operationId: repair_scan_scheduled_brains_repair_scan_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Brains
  /brains/amendment-policy:
    get:
      summary: Brains Amendment Policy
      description: '§3.2 internal read (bot side caches 60s). kind=''all'' returns the full

        resolved matrix for a property in one call.'
      operationId: brains_amendment_policy_brains_amendment_policy_get
      parameters:
      - name: owner_id
        in: query
        required: true
        schema:
          type: string
          title: Owner Id
      - name: kind
        in: query
        required: true
        schema:
          type: string
          title: Kind
      - name: property_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Property Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brains
  /brains/amendment-offer:
    post:
      summary: Brains Amendment Offer
      description: '§3.4 — bot live tool entry: create the request, mint the link when the

        policy allows a fee''d amendment. Everything re-validated server-side.'
      operationId: brains_amendment_offer_brains_amendment_offer_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brains
  /brains/extension-quote:
    post:
      summary: Brains Extension Quote
      description: 'Stay extension (migration 045): availability + price for the extra nights,

        CODE only — the bot''s quote_stay_extension tool. reservation_id may be our

        booking_id, the AB ref, the OTA code or the Channex booking id.'
      operationId: brains_extension_quote_brains_extension_quote_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brains
  /brains/availability-facts:
    post:
      summary: Brains Availability Facts
      description: 'Bot suggest mode: authoritative availability verdict for the thread''s

        home + nearest free windows + same-area alternatives (on an OTA thread:

        only homes live on that platform, by their title there).'
      operationId: brains_availability_facts_brains_availability_facts_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brains
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