Casa Intelligence Public AI API

openapi: 3.2.0
info:
  title: Casa Intelligence Engine Public AI API
  description: Proprietary data ingestion, analysis, and prediction engine for Queensland property development intelligence.
  version: 2.0.0
tags:
- name: public-ai
paths:
  /api/public/v1/health:
    get:
      tags:
      - public-ai
      summary: Public Health
      description: Liveness for the public surface.
      operationId: public_health_api_public_v1_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/public/v1/beacon:
    post:
      tags:
      - public-ai
      summary: Crawler Beacon
      description: 'Records an AI-crawler page READ into the same analytics table as tool calls,

        so `public_api_report.py` shows one unified ''which LLM finds us'' picture —

        both crawlers reading our pages (to cite us) and agents calling our API.


        Fired fire-and-forget by the website''s edge middleware ONLY for AI-crawler

        User-Agents. We still filter server-side to known AI/search bots, so it can''t

        be used to inject junk browser traffic. Returns 204 always (never blocks a page).'
      operationId: crawler_beacon_api_public_v1_beacon_post
      parameters:
      - name: path
        in: query
        required: false
        schema:
          type: string
          description: The site path an AI crawler read.
          default: ''
          title: Path
        description: The site path an AI crawler read.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/public/v1/:
    get:
      tags:
      - public-ai
      summary: Public Root
      description: Discovery root — a machine- and human-readable description of the surface.
      operationId: public_root_api_public_v1__get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/public/v1/openapi.json:
    get:
      tags:
      - public-ai
      summary: Public Openapi
      description: Stable OpenAPI 3.1 contract for the public surface (for auto-wiring).
      operationId: public_openapi_api_public_v1_openapi_json_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/public/v1/property-check:
    get:
      tags:
      - public-ai
      summary: Property Check
      description: 'Indicative planning & development intelligence for a SEQ property.


        Deterministic (no AI in the hot path), cached, and rate-limited. Returns

        zone, overlays, an indicative development/subdivision outlook + Casa score,

        and aggregate nearby-DA activity. **Indicative only — not planning advice and

        not a guarantee of approval.** For the definitive answer, order the $199

        Preliminary Planning Report (see `confirm.url`).'
      operationId: property_check_api_public_v1_property_check_get
      parameters:
      - name: address
        in: query
        required: true
        schema:
          type: string
          minLength: 3
          description: Property address to check (SEQ).
          title: Address
        description: Property address to check (SEQ).
      - name: lat
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            maximum: 90
            minimum: -90
          - type: 'null'
          description: Optional geocoder latitude.
          title: Lat
        description: Optional geocoder latitude.
      - name: lng
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            maximum: 180
            minimum: -180
          - type: 'null'
          description: Optional geocoder longitude.
          title: Lng
        description: Optional geocoder longitude.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPropertyCheck'
        '404':
          description: Address could not be resolved in SEQ coverage.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/public/v1/suburb-da-stats:
    get:
      tags:
      - public-ai
      summary: Suburb Da Stats
      description: 'Cited, aggregate DA statistics for a suburb × development type: number of

        decided applications, approval rate, median days-to-decision and median

        infrastructure charge. Aggregates only. Past decisions do not guarantee

        future outcomes.'
      operationId: suburb_da_stats_api_public_v1_suburb_da_stats_get
      parameters:
      - name: suburb
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          description: Suburb name, e.g. 'Coorparoo'.
          title: Suburb
        description: Suburb name, e.g. 'Coorparoo'.
      - name: dev_type
        in: query
        required: true
        schema:
          type: string
          description: Development type, e.g. subdivision, duplex, townhouse, mcu, kdr_single, secondary_dwelling (aliases like 'granny_flat', 'units' accepted).
          title: Dev Type
        description: Development type, e.g. subdivision, duplex, townhouse, mcu, kdr_single, secondary_dwelling (aliases like 'granny_flat', 'units' accepted).
      - name: lga
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional LGA to disambiguate the suburb.
          title: Lga
        description: Optional LGA to disambiguate the suburb.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSuburbDaStats'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PublicPropertyCheck:
      properties:
        schema_version:
          type: string
          title: Schema Version
          default: '1.0'
        address:
          type: string
          title: Address
        suburb:
          anyOf:
          - type: string
          - type: 'null'
          title: Suburb
        lga:
          type: string
          title: Lga
        zone:
          $ref: '#/components/schemas/PublicZone'
        lot_size_m2:
          anyOf:
          - type: number
          - type: 'null'
          title: Lot Size M2
        overlays:
          items:
            type: string
          type: array
          title: Overlays
        overlays_checked:
          items:
            type: string
          type: array
          title: Overlays Checked
          description: Overlay categories actually checked for this parcel (honesty scoping).
        indicative:
          $ref: '#/components/schemas/PublicIndicative'
        area_da_activity:
          anyOf:
          - $ref: '#/components/schemas/PublicAreaActivity'
          - type: 'null'
        caveat:
          type: string
          title: Caveat
          default: Indicative only, derived from historical council decisions and planning-scheme rules. Subject to site-specific constraints. This is not planning advice and not a guarantee of approval — every application is assessed by the council on its individual merits. For a definitive, site-specific answer, order the $199 Preliminary Planning Report.
        confirm:
          $ref: '#/components/schemas/PublicConfirm'
        attribution:
          $ref: '#/components/schemas/PublicAttribution'
        coverage:
          $ref: '#/components/schemas/PublicCoverage'
        resolved:
          type: boolean
          title: Resolved
          default: true
        cached:
          type: boolean
          title: Cached
          default: false
      type: object
      required:
      - address
      - lga
      - indicative
      - confirm
      title: PublicPropertyCheck
      description: The stable public property-check payload (schema_version 1.x).
    PublicAttribution:
      properties:
        source:
          type: string
          title: Source
          default: Casa Intelligence
        cite_as:
          type: string
          title: Cite As
          default: Casa Intelligence — casaintelligence.com.au
        url:
          type: string
          title: Url
          default: https://www.casaintelligence.com.au
      type: object
      title: PublicAttribution
    PublicIndicative:
      properties:
        development_potential:
          type: string
          title: Development Potential
          description: 'Indicative development potential: ''yes'', ''maybe'' or ''no''.'
        subdivision:
          type: string
          title: Subdivision
          description: 'Indicative subdivision outlook: ''possible'', ''constrained'' or ''unlikely''. Indicative only — confirm with the $199 report.'
        score:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Score
          description: Casa development score (0-100), indicative.
        basis:
          type: string
          title: Basis
          default: Derived from Casa Intelligence's index of decided South East Queensland development applications, council planning-scheme rules, and live council overlay checks — not from this specific site's assessment.
      type: object
      required:
      - development_potential
      - subdivision
      - score
      title: PublicIndicative
      description: Derived, deterministic indicative signals. No LLM, no guarantee.
    PublicZone:
      properties:
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
          description: Planning-scheme zone code, e.g. 'LDR'.
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Human-readable zone name, e.g. 'Low Density Residential'.
      type: object
      title: PublicZone
    PublicCoverage:
      properties:
        region:
          type: string
          title: Region
          default: South East Queensland, Australia
        lgas:
          items:
            type: string
          type: array
          title: Lgas
      type: object
      title: PublicCoverage
    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
    PublicAreaActivity:
      properties:
        radius_m:
          type: integer
          title: Radius M
          default: 750
        years:
          type: integer
          title: Years
          default: 5
        total:
          type: integer
          title: Total
          default: 0
        approved:
          type: integer
          title: Approved
          default: 0
        approval_rate:
          anyOf:
          - type: number
            maximum: 1.0
            minimum: 0.0
          - type: 'null'
          title: Approval Rate
          description: Approved / decided in the local cohort.
        median_days_to_decision:
          anyOf:
          - type: integer
          - type: 'null'
          title: Median Days To Decision
      type: object
      title: PublicAreaActivity
      description: Aggregate DA activity near the parcel. Aggregates ONLY — no raw records.
    PublicConfirm:
      properties:
        product:
          type: string
          title: Product
          default: $199 Preliminary Planning Report
        price_aud:
          type: integer
          title: Price Aud
          default: 199
        url:
          type: string
          title: Url
          description: Order URL for the definitive report for this address.
      type: object
      required:
      - url
      title: PublicConfirm
    PublicSuburbDaStats:
      properties:
        schema_version:
          type: string
          title: Schema Version
          default: '1.0'
        suburb:
          type: string
          title: Suburb
        lga:
          anyOf:
          - type: string
          - type: 'null'
          title: Lga
        dev_type:
          type: string
          title: Dev Type
        dev_type_label:
          type: string
          title: Dev Type Label
        decided:
          type: integer
          title: Decided
          description: Number of decided applications in the cohort.
        approved:
          type: integer
          title: Approved
          default: 0
        approval_rate:
          anyOf:
          - type: number
            maximum: 1.0
            minimum: 0.0
          - type: 'null'
          title: Approval Rate
        median_days_to_decision:
          anyOf:
          - type: integer
          - type: 'null'
          title: Median Days To Decision
        median_infrastructure_charge_aud:
          anyOf:
          - type: integer
          - type: 'null'
          title: Median Infrastructure Charge Aud
        charge_sample_size:
          type: integer
          title: Charge Sample Size
          default: 0
        sample_note:
          type: string
          title: Sample Note
          description: States the sample size and that past decisions do not guarantee outcomes.
        caveat:
          type: string
          title: Caveat
          default: Indicative only, derived from historical council decisions and planning-scheme rules. Subject to site-specific constraints. This is not planning advice and not a guarantee of approval — every application is assessed by the council on its individual merits. For a definitive, site-specific answer, order the $199 Preliminary Planning Report.
        confirm:
          $ref: '#/components/schemas/PublicConfirm'
        attribution:
          $ref: '#/components/schemas/PublicAttribution'
      type: object
      required:
      - suburb
      - dev_type
      - dev_type_label
      - decided
      - sample_note
      - confirm
      title: PublicSuburbDaStats
      description: Aggregate, cited suburb × development-type DA statistics. Aggregates only.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key