Casa Intelligence Possibilities API

openapi: 3.2.0
info:
  title: Casa Intelligence Engine Possibilities API
  description: Proprietary data ingestion, analysis, and prediction engine for Queensland property development intelligence.
  version: 2.0.0
tags:
- name: possibilities
paths:
  /api/v1/possibilities/checkout:
    post:
      tags:
      - possibilities
      summary: Create Possibilities Checkout
      description: 'Create the $199 checkout. Pre-inserts a pending ci_reports row, then a

        Stripe session whose metadata.report_type routes every downstream path.'
      operationId: create_possibilities_checkout_api_v1_possibilities_checkout_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PossibilitiesCheckoutRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app__api__v1__possibilities__CheckoutResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/possibilities/compose:
    post:
      tags:
      - possibilities
      summary: Compose Possibilities
      description: 'Produce a What''s Possible report with no payment — the internal path for

        QA, gifting and accuracy verification.


        Runs the REAL pipeline: the same compose, the same Stage-7 gates, the same

        §I grounding audit and Opus final review, the same ready transition and the

        same ``viewer_url`` (so the QR flyer renders). Two deliberate differences,

        both of which make the row *less* consequential than a sale:


        * **Nothing is emailed.** ``email=None`` — every send in fulfilment is

        gated on it — and a hold does not page ops (``compose_only=True``).

        * **It is not a purchase.** ``amount_cents=0``, no ``stripe_session_id``

        and ``requested_by=''api-compose''``, so the row fails both the

        ``genuine_paid`` gate and the ``genuine_revenue`` reporting predicate.

        That keeps it out of revenue counts, the GA4 purchase event, free-check

        conversion linkage, nurture buyer-skip and the reconcile sweeps.


        Always background: a full possibilities compose with §I legitimately runs

        past the edge-proxy timeout. Poll ``GET /report/{id}``, then fetch

        ``GET /report/{id}/pdf``. A ``needs_review`` status means the accuracy gate

        held it — read ``report_data.possibilities_hold`` for the reasons.'
      operationId: compose_possibilities_api_v1_possibilities_compose_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PossibilitiesComposeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Compose Possibilities Api V1 Possibilities Compose Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /api/v1/possibilities/report/{report_id}/finalize:
    post:
      tags:
      - possibilities
      summary: Finalize Possibilities
      operationId: finalize_possibilities_api_v1_possibilities_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__possibilities__FinalizeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Finalize Possibilities Api V1 Possibilities Report  Report Id  Finalize Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/possibilities/report/{report_id}:
    get:
      tags:
      - possibilities
      summary: Get Possibilities Report
      operationId: get_possibilities_report_api_v1_possibilities_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:
                type: object
                additionalProperties: true
                title: Response Get Possibilities Report Api V1 Possibilities Report  Report Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/possibilities/report/{report_id}/pdf:
    get:
      tags:
      - possibilities
      summary: Get Possibilities Report Pdf
      operationId: get_possibilities_report_pdf_api_v1_possibilities_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:
    AgencyBrandingIn:
      properties:
        agency_name:
          type: string
          maxLength: 120
          minLength: 2
          title: Agency Name
        logo_url:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Logo Url
        phone:
          anyOf:
          - type: string
            maxLength: 80
          - type: 'null'
          title: Phone
        email:
          anyOf:
          - type: string
            maxLength: 80
          - type: 'null'
          title: Email
        website:
          anyOf:
          - type: string
            maxLength: 80
          - type: 'null'
          title: Website
        hours:
          anyOf:
          - type: string
            maxLength: 80
          - type: 'null'
          title: Hours
      type: object
      required:
      - agency_name
      title: AgencyBrandingIn
      description: 'Optional agent co-branding attached at checkout. The report stays

        authored by Casa Intelligence — this only sets who it''s prepared FOR.'
    app__api__v1__possibilities__FinalizeRequest:
      properties:
        session_id:
          type: string
          minLength: 8
          title: Session Id
      type: object
      required:
      - session_id
      title: FinalizeRequest
    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
    PossibilitiesComposeRequest:
      properties:
        property_id:
          type: string
          title: Property Id
          description: ci_properties.id (UUID)
      type: object
      required:
      - property_id
      title: PossibilitiesComposeRequest
      description: 'Compose-only request. Deliberately just the property: the paid path

        always runs the §I review, so there is no flag here that could produce a

        weaker artefact than the one a customer receives.'
    PossibilitiesCheckoutRequest:
      properties:
        property_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Property Id
        address:
          anyOf:
          - type: string
          - type: 'null'
          title: Address
        address_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Address Label
        email:
          type: string
          format: email
          title: Email
        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
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
        org_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Org Id
        branding:
          anyOf:
          - $ref: '#/components/schemas/AgencyBrandingIn'
          - type: 'null'
        free_check_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Free Check Id
        ga_client_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Ga Client Id
        works_intent:
          anyOf:
          - type: string
          - type: 'null'
          title: Works Intent
        phone:
          anyOf:
          - type: string
            maxLength: 60
          - type: 'null'
          title: Phone
      type: object
      required:
      - email
      title: PossibilitiesCheckoutRequest
    app__api__v1__possibilities__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
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key