Casa Intelligence Preliminary API

openapi: 3.2.0
info:
  title: Casa Intelligence Engine Preliminary API
  description: Proprietary data ingestion, analysis, and prediction engine for Queensland property development intelligence.
  version: 2.0.0
tags:
- name: preliminary
paths:
  /api/v1/preliminary/compose:
    post:
      tags:
      - preliminary
      summary: Compose Preliminary
      description: 'Build the preliminary report payload without payment (dashboard + tests).


        ``background=true`` returns immediately with a report id to poll

        (GET /report/{id} → status, GET /report/{id}/pdf once ready) — the

        synchronous path is edge-proxy-timeout-bound at ~300s while a full

        intelligence compose legitimately runs longer.'
      operationId: compose_preliminary_api_v1_preliminary_compose_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreliminaryComposeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Compose Preliminary Api V1 Preliminary Compose Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /api/v1/preliminary/checkout:
    post:
      tags:
      - preliminary
      summary: Create Preliminary Checkout
      description: 'Create a $199 Stripe one-time checkout for a preliminary planning report.


        Pre-inserts a pending ci_reports row (carrying the dev intent in report_data

        so fulfilment can compose), then creates the Stripe session. Mirrors the

        working consumer report-checkout flow.'
      operationId: create_preliminary_checkout_api_v1_preliminary_checkout_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreliminaryCheckoutRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app__api__v1__preliminary__CheckoutResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/preliminary/report/{report_id}/intent:
    post:
      tags:
      - preliminary
      summary: Post Payment Intent
      description: 'The buyer''s own words, collected AFTER payment (Conversion Recovery

        Spec W8.5): the free-text plan was a pre-payment field on every path and

        the pre-payment path is now email and payment only. The desk reads

        report_data.works_intent, so it lands in the same place. Authorised by the

        Stripe session that paid for this report, exactly as finalize is.'
      operationId: post_payment_intent_api_v1_preliminary_report__report_id__intent_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/PostPaymentIntent'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Post Payment Intent Api V1 Preliminary Report  Report Id  Intent Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/preliminary/report/{report_id}/finalize:
    post:
      tags:
      - preliminary
      summary: Finalize Preliminary
      description: Verify Stripe payment then generate + store the report. Idempotent.
      operationId: finalize_preliminary_api_v1_preliminary_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__preliminary__FinalizeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/preliminary/report/{report_id}:
    get:
      tags:
      - preliminary
      summary: Get Preliminary Report
      description: Status + report_data for the public web view (polled after Stripe redirect).
      operationId: get_preliminary_report_api_v1_preliminary_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/ReportResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/preliminary/report/{report_id}/pdf:
    get:
      tags:
      - preliminary
      summary: Get Preliminary Report Pdf
      description: 'Downloadable branded PDF of a paid + ready preliminary report.


        Access model matches the JSON GET: possession of the report uuid. The PDF

        is regenerated per request from the stored ``report_data`` payload (a

        deterministic Typst render, well under a second — no storage round-trip

        needed) and streamed back as an attachment.'
      operationId: get_preliminary_report_pdf_api_v1_preliminary_report__report_id__pdf_get
      parameters:
      - name: report_id
        in: path
        required: true
        schema:
          type: string
          title: Report Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    app__api__v1__preliminary__CheckoutResponse:
      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: CheckoutResponse
    ReportResponse:
      properties:
        id:
          type: string
          title: Id
        property_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Property Id
        status:
          type: string
          title: Status
        paid:
          type: boolean
          title: Paid
        report_type:
          type: string
          title: Report Type
        report_data:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Report Data
        requested_email:
          anyOf:
          - type: string
          - type: 'null'
          title: Requested Email
        created_at:
          type: string
          title: Created At
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
        agent:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Agent
      type: object
      required:
      - id
      - property_id
      - status
      - paid
      - report_type
      - created_at
      title: ReportResponse
    PostPaymentIntent:
      properties:
        stripe_session_id:
          type: string
          title: Stripe Session Id
        works_intent:
          type: string
          maxLength: 2000
          minLength: 1
          title: Works Intent
      type: object
      required:
      - stripe_session_id
      - works_intent
      title: PostPaymentIntent
    app__api__v1__preliminary__FinalizeRequest:
      properties:
        stripe_session_id:
          type: string
          title: Stripe Session Id
      type: object
      required:
      - stripe_session_id
      title: FinalizeRequest
    PreliminaryCheckoutRequest:
      properties:
        email:
          type: string
          format: email
          title: Email
        property_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Property Id
          description: UUID of ci_properties row, if already resolved
        address:
          anyOf:
          - type: string
          - type: 'null'
          title: Address
          description: SEQ address — resolved server-side if property_id absent
        dev_type:
          type: string
          title: Dev Type
          default: kdr_single
        unit_count:
          type: integer
          maximum: 500.0
          minimum: 1.0
          title: Unit Count
          default: 1
        works_intent:
          anyOf:
          - type: string
          - type: 'null'
          title: Works Intent
        address_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Address Label
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
        org_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Org Id
        success_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Success Url
        cancel_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Cancel Url
        utm:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Utm
          description: Marketing attribution pairs (utm_source/utm_medium/utm_campaign/utm_term/utm_content/referrer). Sanitized server-side.
        free_check_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Free Check Id
          description: ci_free_checks id this purchase originated from, for conversion linkage
        ga_client_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Ga Client Id
          description: GA4 client id from the buyer's _ga cookie, for server-side purchase events
        phone:
          anyOf:
          - type: string
            maxLength: 60
          - type: 'null'
          title: Phone
          description: Optional, and it stays optional. Baymard measured 14 per cent of shoppers refusing to give a phone number to an online store, so a required field costs buyers and returns junk from some who stay. Travels to the desk so a person can call about the property when the buyer wants that.
        neighbour_property_ids:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 12
          - type: 'null'
          title: Neighbour Property Ids
          description: Adjoining lot UUIDs to amalgamate with the subject into one combined-site report. Validated (contiguous + uniform controls) before charging; mixed-control selections are blocked at checkout.
      type: object
      required:
      - email
      title: PreliminaryCheckoutRequest
    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
    PreliminaryComposeRequest:
      properties:
        property_id:
          type: string
          title: Property Id
          description: ci_properties.id (UUID)
        dev_type:
          type: string
          title: Dev Type
          description: 'One of: subdivision, townhouse, duplex, mcu, kdr_single, secondary_dwelling.'
          default: kdr_single
        unit_count:
          type: integer
          maximum: 500.0
          minimum: 1.0
          title: Unit Count
          default: 1
        works_intent:
          anyOf:
          - type: string
          - type: 'null'
          title: Works Intent
          description: Free-text description of the works the applicant wants to do.
        combined_property_ids:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 12
          - type: 'null'
          title: Combined Property Ids
          description: Adjoining lot UUIDs to amalgamate with property_id into one combined-site report (admin verification of the paid amalgamation path).
        include_intelligence:
          type: boolean
          title: Include Intelligence
          description: When False, skip the AI reasoning/§I passes and compose the deterministic report only — free + fast, for structural/visual QA of the PDF (site plan, layout, amalgamation) without AI spend.
          default: true
        background:
          type: boolean
          title: Background
          description: 'Run compose off the request path: returns {report_id, status: ''generating''} immediately; poll GET /report/{id} until status=''ready'', then GET /report/{id}/pdf. Use this for full-intelligence composes — synchronous compose can exceed the edge proxy''s ~300s request timeout and return a 502 with the work lost.'
          default: false
        final_review:
          type: boolean
          title: Final Review
          description: 'Also run the §I Opus final-review pass on the composed payload (normally paid-path only). Lets §I be verified end-to-end via this admin endpoint without a Stripe purchase: edits/flags log to ci_report_review_edits and the payload carries the final_review stamp. Only honoured with background=true.'
          default: false
      type: object
      required:
      - property_id
      title: PreliminaryComposeRequest
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key