Casa Intelligence Consumer API

openapi: 3.2.0
info:
  title: Casa Intelligence Engine Consumer API
  description: Proprietary data ingestion, analysis, and prediction engine for Queensland property development intelligence.
  version: 2.0.0
tags:
- name: consumer
paths:
  /api/v1/consumer/log-search:
    post:
      tags:
      - consumer
      summary: Log Search
      description: 'Log a public property search to ci_events. Fire-and-forget — never blocks

        the page render. Powers the data flywheel: every search is intent signal.


        No auth required. We capture anonymous_id (from session_id) + IP-derived city

        for aggregate analysis without retaining PII.'
      operationId: log_search_api_v1_consumer_log_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogSearchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleAck'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/consumer/subscribe-alert:
    post:
      tags:
      - consumer
      summary: Subscribe Alert
      description: 'Capture email + property to alert on (DA activity, comparable sales, etc.).


        Inserts into ci_leads with source=''property_alert''. Future Casa Pro

        subscription upsell pulls from this list. Idempotent on (email, property_id) —

        duplicate submits update name + return the existing row.'
      operationId: subscribe_alert_api_v1_consumer_subscribe_alert_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribeAlertRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleAck'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/consumer/report-checkout:
    post:
      tags:
      - consumer
      summary: Create Report Checkout
      description: 'Create a Stripe one-time checkout session for a $29 property profile PDF.


        Flow:

        1. Insert a pending ci_reports row (status=''pending'', paid=False)

        2. Create Stripe Checkout Session with price = STRIPE_PRICE_PROPERTY_PROFILE

        3. Return the checkout URL — frontend redirects user to Stripe

        4. On Stripe webhook (checkout.session.completed), update ci_reports.paid=True

        and trigger PDF generation (background task)

        5. User is redirected back to /report/{report_id} which polls for ready'
      operationId: create_report_checkout_api_v1_consumer_report_checkout_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportCheckoutRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportCheckoutResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/consumer/report/{report_id}/finalize:
    post:
      tags:
      - consumer
      summary: Finalize Report
      description: 'Verify Stripe payment + mark report as ready.


        Called by the frontend after Stripe redirects the user back to

        /report/{id}?session=cs_xxx. We:

        1. Look up the ci_reports row (must exist, must match Stripe session.metadata.report_id)

        2. Fetch the Stripe session and verify payment_status == ''paid''

        3. Update ci_reports.paid=true, status=''ready'', completed_at=NOW

        4. Return current status


        Idempotent — calling twice is safe.


        The actual report content is rendered at view time using build_deal_sheet

        against the property_id — no PDF generation needed. The customer paid for

        permanent access to the live intelligence on this property.'
      operationId: finalize_report_api_v1_consumer_report__report_id__finalize_post
      parameters:
      - name: report_id
        in: path
        required: true
        schema:
          type: string
          title: Report Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/app__api__v1__consumer__FinalizeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/consumer/lots-in-bbox:
    get:
      tags:
      - consumer
      summary: Lots In Bbox
      description: 'Return GeoJSON FeatureCollection of lots intersecting the viewport bbox.


        Drives the public lots map. Two layers:

        - registered: ci_properties (cadastral, blue rendering on map)

        - pre_registered: ci_estate_lots (extracted from subdivision plans, yellow rendering)


        Bbox is in EPSG:4326 (WGS84 lon/lat). Limit is per layer to keep payloads

        manageable; a typical zoomed-in residential view returns 50-500 features.'
      operationId: lots_in_bbox_api_v1_consumer_lots_in_bbox_get
      parameters:
      - name: west
        in: query
        required: true
        schema:
          type: number
          title: West
      - name: south
        in: query
        required: true
        schema:
          type: number
          title: South
      - name: east
        in: query
        required: true
        schema:
          type: number
          title: East
      - name: north
        in: query
        required: true
        schema:
          type: number
          title: North
      - name: kinds
        in: query
        required: false
        schema:
          type: string
          default: both
          title: Kinds
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 2000
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Lots In Bbox Api V1 Consumer Lots In Bbox Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/consumer/report/{report_id}:
    get:
      tags:
      - consumer
      summary: Get Report Status
      description: 'Check report status — frontend polls this after Stripe redirect.


        Statuses progress: pending → paid → generating → ready | failed

        Returns download_url only when status=''ready''.'
      operationId: get_report_status_api_v1_consumer_report__report_id__get
      parameters:
      - name: report_id
        in: path
        required: true
        schema:
          type: string
          title: Report Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SimpleAck:
      properties:
        ok:
          type: boolean
          title: Ok
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
      type: object
      required:
      - ok
      title: SimpleAck
    app__api__v1__consumer__FinalizeRequest:
      properties:
        stripe_session_id:
          type: string
          title: Stripe Session Id
      type: object
      required:
      - stripe_session_id
      title: FinalizeRequest
    LogSearchRequest:
      properties:
        address:
          type: string
          maxLength: 400
          minLength: 3
          title: Address
        property_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Property Id
        suburb:
          anyOf:
          - type: string
          - type: 'null'
          title: Suburb
        lga:
          anyOf:
          - type: string
          - type: 'null'
          title: Lga
        referrer:
          anyOf:
          - type: string
          - type: 'null'
          title: Referrer
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
        source:
          type: string
          title: Source
          default: consumer_property_search
        intent_signals:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Intent Signals
      type: object
      required:
      - address
      title: LogSearchRequest
    ReportCheckoutRequest:
      properties:
        property_id:
          type: string
          title: Property Id
          description: UUID of ci_properties row
        email:
          type: string
          format: email
          title: Email
        address_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Address Label
        success_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Success Url
        cancel_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Cancel Url
      type: object
      required:
      - property_id
      - email
      title: ReportCheckoutRequest
    ReportStatusResponse:
      properties:
        id:
          type: string
          title: Id
        property_id:
          type: string
          title: Property Id
        status:
          type: string
          title: Status
        paid:
          type: boolean
          title: Paid
        download_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Download Url
        requested_email:
          anyOf:
          - type: string
          - type: 'null'
          title: Requested Email
        generation_time_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Generation Time Ms
        created_at:
          type: string
          title: Created At
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
      type: object
      required:
      - id
      - property_id
      - status
      - paid
      - download_url
      - requested_email
      - generation_time_ms
      - created_at
      - completed_at
      title: ReportStatusResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SubscribeAlertRequest:
      properties:
        email:
          type: string
          format: email
          title: Email
        address:
          type: string
          maxLength: 400
          minLength: 3
          title: Address
        property_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Property Id
        suburb:
          anyOf:
          - type: string
          - type: 'null'
          title: Suburb
        lga:
          anyOf:
          - type: string
          - type: 'null'
          title: Lga
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        source:
          type: string
          title: Source
          default: property_alert
      type: object
      required:
      - email
      - address
      title: SubscribeAlertRequest
    ReportCheckoutResponse:
      properties:
        checkout_url:
          type: string
          title: Checkout Url
        session_id:
          type: string
          title: Session Id
        report_id:
          type: string
          title: Report Id
      type: object
      required:
      - checkout_url
      - session_id
      - report_id
      title: ReportCheckoutResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key