Casa Intelligence Property API

openapi: 3.2.0
info:
  title: Casa Intelligence Engine Property API
  description: Proprietary data ingestion, analysis, and prediction engine for Queensland property development intelligence.
  version: 2.0.0
tags:
- name: property
paths:
  /api/v1/property/lookup:
    get:
      tags:
      - property
      summary: Lookup Property
      description: 'Look up a property by street address.


        1. Geocodes the address using ArcGIS World Geocoder

        2. Finds the matching ci_properties record (lot/plan match or nearest centroid)

        3. Returns the full property data + zone rules + DA counts


        This is the primary entry point for the website checkout flow.'
      operationId: lookup_property_api_v1_property_lookup_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: address
        in: query
        required: true
        schema:
          type: string
          minLength: 3
          description: Street address to search for
          title: Address
        description: Street address to search for
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyLookupResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/property/resolve:
    get:
      tags:
      - property
      summary: Resolve Property
      description: 'Resolve an address to a Casa-Engine property_id.

        Lightweight version of /lookup — returns ONLY the UUID + matched

        address (not the full enrichment payload). The Chrome extension

        calls this before /api/v1/property/{id} so it can switch to

        UUID-based lookups without paying the full lookup cost.'
      operationId: resolve_property_api_v1_property_resolve_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: address
        in: query
        required: true
        schema:
          type: string
          minLength: 3
          description: Address to resolve to a property UUID
          title: Address
        description: Address to resolve to a property UUID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyResolveResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - property
      summary: Resolve Property
      description: 'Take an address (or lat/lng) and return the ci_properties.id that

        represents that parcel. Self-heals the row if the parcel isn''t in

        our index yet.


        Body:

        {

        "address": "5 Some Street, Eumundi QLD 4562", // optional

        "lat": -26.45297, // optional

        "lng": 152.97092 // optional

        }


        At least one of (address, lat+lng) is required.'
      operationId: resolve_property_api_v1_property_resolve_post
      security:
      - APIKeyHeader: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Resolve Property Api V1 Property Resolve Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/property/{property_id}:
    get:
      tags:
      - property
      summary: Get Property
      description: 'Get full property intelligence by ID.


        Sequential (safe) execution, with per-stage timing for visibility:


        First attempt at parallelisation via asyncio.gather on a single

        AsyncSession produced `asyncpg.InterfaceError: connection is closed`

        in production — SQLAlchemy 2.0 async sessions DO NOT support

        concurrent statements on a single session, even for read-only

        queries. Reverted to sequential. The dedup of `ci_rea_listings`

        fetch (passed to both score + intent helpers) is the real durable

        win — saves one round-trip per request.


        Per-stage timing logged at INFO with a tag the operator can grep:

        `[property/get] property_id=... t_fetch=Xms t_zone=Yms t_da=Zms

        t_nearby=Wms t_rea=Vms t_score=Sms t_intent=Ims t_total=Tms`.

        Once we have several real samples in Railway, the dominant cost

        will be obvious — almost certainly `t_score` (score_rea_listing

        fans out into _fetch_property_scoring_inputs + forecast_da_pathway).'
      operationId: get_property_api_v1_property__property_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: property_id
        in: path
        required: true
        schema:
          type: string
          title: Property Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyLookupResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/property/{property_id}/pricing-assessment:
    get:
      tags:
      - property
      summary: Pricing Assessment
      description: 'Lightweight pricing assessment — comparable sales + suburb

        facets, no Gemini Vision or per-signal breakdown.


        This is the public/free-tier version of the Casa Daily pricing

        engine. The full version (with Vision + multi-signal blend)

        lives behind the cd_subscriptions gate at

        casadaily.com.au/api/extension/pricing-assessment. Both surface

        the same shape so the extension can render either one with the

        same React component.'
      operationId: pricing_assessment_api_v1_property__property_id__pricing_assessment_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: property_id
        in: path
        required: true
        schema:
          type: string
          title: Property Id
      - name: asking_price
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Override asking price (defaults to current REA listing)
          title: Asking Price
        description: Override asking price (defaults to current REA listing)
      - name: bedrooms
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Override subject bedroom count. Used as a fallback when ci_rea_listings has no row or its bedrooms field is null. Callers (Chrome extension, dashboard) should pass the count extracted from the REA/Domain listing page — without it the engine can't bedroom-match comps and the fair value gets pulled toward 3-bed median territory on 4-bed listings.
          title: Bedrooms
        description: Override subject bedroom count. Used as a fallback when ci_rea_listings has no row or its bedrooms field is null. Callers (Chrome extension, dashboard) should pass the count extracted from the REA/Domain listing page — without it the engine can't bedroom-match comps and the fair value gets pulled toward 3-bed median territory on 4-bed listings.
      - name: building_area_m2
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Override subject building area (m²). Same rationale as `bedrooms` — used when ci_rea_listings doesn't have it. Drives the building-scale similarity score and unblocks the scale-uplift signal.
          title: Building Area M2
        description: Override subject building area (m²). Same rationale as `bedrooms` — used when ci_rea_listings doesn't have it. Drives the building-scale similarity score and unblocks the scale-uplift signal.
      - name: year_built
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 2100
            minimum: 1800
          - type: 'null'
          description: Year the dwelling was built. Extracted by the Chrome extension from the REA/Domain listing DOM. Used as a structured build-recency signal — more reliable than the description-keyword / photo-grade inference fallbacks. Surfaced in the rationale and feeds a recency uplift in downstream consumers.
          title: Year Built
        description: Year the dwelling was built. Extracted by the Chrome extension from the REA/Domain listing DOM. Used as a structured build-recency signal — more reliable than the description-keyword / photo-grade inference fallbacks. Surfaced in the rationale and feeds a recency uplift in downstream consumers.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PricingAssessmentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/property/{property_id}/context:
    get:
      tags:
      - property
      summary: Get Property Context
      description: 'Assemble the full context package for a property.


        This is the rich data payload that gets sent to the AI reasoning engine.

        Includes: property data, zone rules, overlays, DA history, nearby DAs,

        localised insights, and approval statistics.'
      operationId: get_property_context_api_v1_property__property_id__context_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: property_id
        in: path
        required: true
        schema:
          type: string
          title: Property Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyContextPackage'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ZoneRules:
      properties:
        zone_code:
          type: string
          title: Zone Code
        zone_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Zone Name
        lga:
          type: string
          title: Lga
        min_lot_area_m2:
          anyOf:
          - type: number
          - type: 'null'
          title: Min Lot Area M2
        min_frontage_m:
          anyOf:
          - type: number
          - type: 'null'
          title: Min Frontage M
        max_site_cover_pct:
          anyOf:
          - type: number
          - type: 'null'
          title: Max Site Cover Pct
        max_height_m:
          anyOf:
          - type: number
          - type: 'null'
          title: Max Height M
        max_storeys:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Storeys
        min_setback_front_m:
          anyOf:
          - type: number
          - type: 'null'
          title: Min Setback Front M
        min_setback_side_m:
          anyOf:
          - type: number
          - type: 'null'
          title: Min Setback Side M
        min_setback_rear_m:
          anyOf:
          - type: number
          - type: 'null'
          title: Min Setback Rear M
        allows_subdivision:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Allows Subdivision
        dual_occ_permitted:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Dual Occ Permitted
        dual_occ_min_parent_m2:
          anyOf:
          - type: number
          - type: 'null'
          title: Dual Occ Min Parent M2
        dual_occ_min_result_m2:
          anyOf:
          - type: number
          - type: 'null'
          title: Dual Occ Min Result M2
        multi_unit_permitted:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Multi Unit Permitted
        multi_unit_density:
          anyOf:
          - type: number
          - type: 'null'
          title: Multi Unit Density
        notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Notes
      type: object
      required:
      - zone_code
      - lga
      title: ZoneRules
      description: Planning rules for a property's zone.
    ComparableDA:
      properties:
        id:
          type: string
          title: Id
        application_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Application Number
        address:
          anyOf:
          - type: string
          - type: 'null'
          title: Address
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        application_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Application Type
        category:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
        lodgement_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Lodgement Date
        decision_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Decision Date
        decision:
          anyOf:
          - type: string
          - type: 'null'
          title: Decision
        days_to_decision:
          anyOf:
          - type: integer
          - type: 'null'
          title: Days To Decision
        lots_proposed:
          anyOf:
          - type: integer
          - type: 'null'
          title: Lots Proposed
        lots_existing:
          anyOf:
          - type: integer
          - type: 'null'
          title: Lots Existing
        dwellings_proposed:
          anyOf:
          - type: integer
          - type: 'null'
          title: Dwellings Proposed
        storeys_proposed:
          anyOf:
          - type: integer
          - type: 'null'
          title: Storeys Proposed
        zone_at_lodgement:
          anyOf:
          - type: string
          - type: 'null'
          title: Zone At Lodgement
        area_m2:
          anyOf:
          - type: number
          - type: 'null'
          title: Area M2
        distance_m:
          anyOf:
          - type: number
          - type: 'null'
          title: Distance M
        relevance_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Relevance Score
      type: object
      required:
      - id
      title: ComparableDA
      description: A DA application returned as a comparable.
    LocalisedInsight:
      properties:
        insight_type:
          type: string
          title: Insight Type
        headline:
          type: string
          title: Headline
        detail:
          type: string
          title: Detail
        evidence_count:
          type: integer
          title: Evidence Count
          default: 0
        relevance_score:
          type: number
          title: Relevance Score
          default: 0.0
        radius_m:
          type: integer
          title: Radius M
          default: 0
      type: object
      required:
      - insight_type
      - headline
      - detail
      title: LocalisedInsight
      description: A property-specific insight derived from spatial DA analysis.
    PropertyContextPackage:
      properties:
        property:
          $ref: '#/components/schemas/PropertySummary'
        zone_rules:
          anyOf:
          - $ref: '#/components/schemas/ZoneRules'
          - type: 'null'
        overlays:
          items:
            $ref: '#/components/schemas/PropertyOverlay'
          type: array
          title: Overlays
          default: []
        da_history:
          items:
            $ref: '#/components/schemas/ComparableDA'
          type: array
          title: Da History
          default: []
        nearby_das:
          items:
            $ref: '#/components/schemas/ComparableDA'
          type: array
          title: Nearby Das
          default: []
        insights:
          items:
            $ref: '#/components/schemas/LocalisedInsight'
          type: array
          title: Insights
          default: []
        approval_stats:
          anyOf:
          - $ref: '#/components/schemas/TrendStat'
          - type: 'null'
        zone_trend:
          anyOf:
          - $ref: '#/components/schemas/TrendStat'
          - type: 'null'
      type: object
      required:
      - property
      title: PropertyContextPackage
      description: 'The full context package assembled for a property.

        This is what gets sent to the AI reasoning engine.'
    PropertyOverlay:
      properties:
        code:
          type: string
          title: Code
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        constraint_summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Constraint Summary
      type: object
      required:
      - code
      title: PropertyOverlay
      description: A single overlay affecting a property.
    TrendStat:
      properties:
        total_das:
          type: integer
          title: Total Das
          default: 0
        approved:
          type: integer
          title: Approved
          default: 0
        refused:
          type: integer
          title: Refused
          default: 0
        pending:
          type: integer
          title: Pending
          default: 0
        withdrawn:
          type: integer
          title: Withdrawn
          default: 0
        approval_rate:
          anyOf:
          - type: number
          - type: 'null'
          title: Approval Rate
        avg_days_to_decision:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Days To Decision
        avg_lots_proposed:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Lots Proposed
        most_common_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Most Common Type
      type: object
      title: TrendStat
      description: Aggregate DA statistics for an LGA or zone.
    PricingComparable:
      properties:
        address:
          anyOf:
          - type: string
          - type: 'null'
          title: Address
        sale_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Sale Date
        sale_price:
          anyOf:
          - type: number
          - type: 'null'
          title: Sale Price
        distance_m:
          anyOf:
          - type: number
          - type: 'null'
          title: Distance M
        land_area_m2:
          anyOf:
          - type: number
          - type: 'null'
          title: Land Area M2
        bedrooms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Bedrooms
        similarity_pct:
          type: integer
          title: Similarity Pct
          default: 0
      type: object
      title: PricingComparable
      description: A single comparable sale, similarity-weighted.
    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
    PropertyResolveResponse:
      properties:
        property_id:
          type: string
          title: Property Id
        address:
          anyOf:
          - type: string
          - type: 'null'
          title: Address
        cadastral_address:
          anyOf:
          - type: string
          - type: 'null'
          title: Cadastral Address
        suburb:
          anyOf:
          - type: string
          - type: 'null'
          title: Suburb
        lga:
          anyOf:
          - type: string
          - type: 'null'
          title: Lga
        matched_via:
          type: string
          title: Matched Via
      type: object
      required:
      - property_id
      - matched_via
      title: PropertyResolveResponse
      description: 'Lightweight response for resolving an address to a property_id.

        The Chrome extension calls this before /api/v1/property/{id} to

        avoid the full enrichment overhead just to find the UUID.'
    PricingAssessmentResponse:
      properties:
        property_id:
          type: string
          title: Property Id
        address:
          anyOf:
          - type: string
          - type: 'null'
          title: Address
        zone_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Zone Code
        bedrooms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Bedrooms
        asking_price:
          anyOf:
          - type: integer
          - type: 'null'
          title: Asking Price
        asking_price_source:
          anyOf:
          - type: string
          - type: 'null'
          title: Asking Price Source
        fair_value_low:
          anyOf:
          - type: integer
          - type: 'null'
          title: Fair Value Low
        fair_value_mid:
          anyOf:
          - type: integer
          - type: 'null'
          title: Fair Value Mid
        fair_value_high:
          anyOf:
          - type: integer
          - type: 'null'
          title: Fair Value High
        delta_pct_vs_mid:
          anyOf:
          - type: number
          - type: 'null'
          title: Delta Pct Vs Mid
        verdict:
          type: string
          title: Verdict
          default: unknown
        bargaining_room_aud:
          anyOf:
          - type: integer
          - type: 'null'
          title: Bargaining Room Aud
        recommended_offer_low:
          anyOf:
          - type: integer
          - type: 'null'
          title: Recommended Offer Low
        recommended_offer_high:
          anyOf:
          - type: integer
          - type: 'null'
          title: Recommended Offer High
        comparables_used:
          type: integer
          title: Comparables Used
          default: 0
        zone_facet_median:
          anyOf:
          - type: integer
          - type: 'null'
          title: Zone Facet Median
        bedroom_facet_median:
          anyOf:
          - type: integer
          - type: 'null'
          title: Bedroom Facet Median
        suburb_median:
          anyOf:
          - type: integer
          - type: 'null'
          title: Suburb Median
        bathrooms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Bathrooms
        year_built:
          anyOf:
          - type: integer
          - type: 'null'
          title: Year Built
        days_on_market:
          anyOf:
          - type: integer
          - type: 'null'
          title: Days On Market
        rationale:
          items:
            type: string
          type: array
          title: Rationale
          default: []
        top_comparables:
          items:
            $ref: '#/components/schemas/PricingComparable'
          type: array
          title: Top Comparables
          default: []
        tier:
          type: string
          title: Tier
          default: lite
      type: object
      required:
      - property_id
      title: PricingAssessmentResponse
      description: 'Lightweight pricing assessment — comparable-sales + suburb-

        facets blend, NO Gemini Vision (saves cost so it''s safe to expose

        publicly with X-API-Key gating only).


        Same shape as Casa Daily''s PricingAssessmentPayload so the

        extension can render the assessment with the same component

        whether the user is signed in or not.'
    PropertyScore:
      properties:
        casa_score:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Casa Score
          default: 0
        tier:
          anyOf:
          - type: string
          - type: 'null'
          title: Tier
        tier_color:
          anyOf:
          - type: string
          - type: 'null'
          title: Tier Color
        tier_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Tier Label
        components:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Components
        rationale:
          anyOf:
          - type: string
          - type: 'null'
          title: Rationale
      type: object
      title: PropertyScore
      description: 'Casa Score block — same scoring used by widget endpoint and

        the Casa Daily dashboard so both products show the same number.'
    PropertyLookupResponse:
      properties:
        property:
          $ref: '#/components/schemas/PropertySummary'
        zone_rules:
          anyOf:
          - $ref: '#/components/schemas/ZoneRules'
          - type: 'null'
        score:
          anyOf:
          - $ref: '#/components/schemas/PropertyScore'
          - type: 'null'
        da_count:
          type: integer
          title: Da Count
          default: 0
        nearby_da_count:
          type: integer
          title: Nearby Da Count
          default: 0
        has_development_potential:
          type: boolean
          title: Has Development Potential
          default: false
        listing_intent_subdivision:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Listing Intent Subdivision
        listing_intent_keywords:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Listing Intent Keywords
      type: object
      required:
      - property
      title: PropertyLookupResponse
      description: Full response from property lookup endpoint.
    PropertyLocation:
      properties:
        latitude:
          type: number
          title: Latitude
        longitude:
          type: number
          title: Longitude
      type: object
      required:
      - latitude
      - longitude
      title: PropertyLocation
      description: Geographic coordinates for a property.
    PropertySummary:
      properties:
        id:
          type: string
          title: Id
        lot_plan:
          type: string
          title: Lot Plan
        address:
          anyOf:
          - type: string
          - type: 'null'
          title: Address
        suburb:
          anyOf:
          - type: string
          - type: 'null'
          title: Suburb
        postcode:
          anyOf:
          - type: string
          - type: 'null'
          title: Postcode
        lga:
          type: string
          title: Lga
        state:
          type: string
          title: State
          default: QLD
        area_m2:
          anyOf:
          - type: number
          - type: 'null'
          title: Area M2
        frontage_m:
          anyOf:
          - type: number
          - type: 'null'
          title: Frontage M
        depth_m:
          anyOf:
          - type: number
          - type: 'null'
          title: Depth M
        shape_factor:
          anyOf:
          - type: number
          - type: 'null'
          title: Shape Factor
        is_corner:
          type: boolean
          title: Is Corner
          default: false
        is_battle_axe:
          type: boolean
          title: Is Battle Axe
          default: false
        location:
          anyOf:
          - $ref: '#/components/schemas/PropertyLocation'
          - type: 'null'
        zone_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Zone Code
        zone_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Zone Name
        overlays:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Overlays
        is_in_pda:
          type: boolean
          title: Is In Pda
          default: false
        pda_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Pda Name
        subdivision_eligible:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Subdivision Eligible
        subdivision_pathway:
          anyOf:
          - type: string
          - type: 'null'
          title: Subdivision Pathway
        max_lots:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Lots
        da_approval_probability:
          anyOf:
          - type: number
          - type: 'null'
          title: Da Approval Probability
        development_potential:
          anyOf:
          - type: number
          - type: 'null'
          title: Development Potential
        estimated_uplift_low:
          anyOf:
          - type: number
          - type: 'null'
          title: Estimated Uplift Low
        estimated_uplift_high:
          anyOf:
          - type: number
          - type: 'null'
          title: Estimated Uplift High
        data_quality:
          anyOf:
          - type: number
          - type: 'null'
          title: Data Quality
        last_enriched:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Enriched
      type: object
      required:
      - id
      - lot_plan
      - lga
      title: PropertySummary
      description: Core property data returned from lookup.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key