Casa Intelligence Rea Live API

openapi: 3.2.0
info:
  title: Casa Intelligence Engine Rea Live API
  description: Proprietary data ingestion, analysis, and prediction engine for Queensland property development intelligence.
  version: 2.0.0
tags:
- name: rea-live
paths:
  /api/v1/rea-live/search:
    post:
      tags:
      - rea-live
      summary: Queue Live Scrape
      description: 'Queue a live REA scrape for a suburb.


        Returns immediately with a job_id. The actual Playwright (or

        ScrapFly cascade) scrape runs in the background and typically

        completes in 45-90s. Poll via GET /rea-live/search/{job_id}.


        If the same suburb was scraped in the last 30 minutes, the existing

        job''s result is returned (no re-scrape). If 3+ jobs are already in

        flight, a rate_limited response is returned — retry after 60s.'
      operationId: queue_live_scrape_api_v1_rea_live_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScrapeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrapeQueuedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /api/v1/rea-live/search/{job_id}:
    get:
      tags:
      - rea-live
      summary: Get Live Scrape Result
      description: 'Fetch the current status + (when status=''done'') listings for a job.


        Status lifecycle: queued → running → done | failed.

        When done, listings_found > 0 means new listings were upserted into

        ci_rea_listings AND the joined listings array is populated. When

        listings_found == 0, the scrape succeeded but the suburb returned

        no matching properties for the given filters.'
      operationId: get_live_scrape_result_api_v1_rea_live_search__job_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrapeResultResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ScrapeListing:
      properties:
        id:
          anyOf:
          - type: string
          - type: string
            format: uuid
          - type: 'null'
          title: Id
        property_id:
          anyOf:
          - type: string
          - type: string
            format: uuid
          - type: 'null'
          title: Property Id
        address_raw:
          anyOf:
          - type: string
          - type: 'null'
          title: Address Raw
        price_current:
          anyOf:
          - type: integer
          - type: 'null'
          title: Price Current
        land_area_m2:
          anyOf:
          - type: number
          - type: 'null'
          title: Land Area M2
        development_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Development Score
        canonical_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Canonical Url
      additionalProperties: true
      type: object
      title: ScrapeListing
      description: "One row of a live REA scrape's results.\n\nThe agent_tools_hotspots.get_rea_search_results function returns\nraw `ci_rea_listings` rows whose DB column names DON'T match the\nPydantic field names this model originally defined, AND whose\ntypes include Python UUIDs that Pydantic 2.13 will NOT silently\ncoerce to str. Both mismatches need handling so the endpoint\ndoesn't 422.\n\nHistory (2026-05-23):\n  - First 422: \"listings.0.listing_id Field required\" — model\n    required a field that didn't exist in the data shape. Fixed\n    by making everything optional + adding `alias` for the\n    renamed columns.\n  - Second 422 (after first fix): \"listings.0.id Input should\n    be a valid string [type=string_type, input_value=UUID(...)]\"\n    — Pydantic 2.13 type-strictness rejects UUID for a str-typed\n    field even in lax mode. Fixed by widening the type to\n    `str | UUID | None` and adding a `field_validator` that\n    stringifies UUIDs explicitly.\n\n`extra=\"allow\"` lets the additional DB columns (suburb, lga,\nbedrooms, bathrooms, car_spaces, building_area_m2, price_display,\nprice_low, listed_date, last_seen_date, score_tier, score_summary,\nstatus, thumbnail_url, property_type) pass through unmolested.\ncasa-daily's strict TypeScript type just ignores fields it\ndoesn't know about."
    ScrapeQueuedResponse:
      properties:
        job_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Job Id
        existing_job_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Existing Job Id
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        suburb:
          type: string
          title: Suburb
        postcode:
          anyOf:
          - type: string
          - type: 'null'
          title: Postcode
        lga:
          anyOf:
          - type: string
          - type: 'null'
          title: Lga
        rea_search_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Rea Search Url
        expected_duration_s:
          anyOf:
          - type: integer
          - type: 'null'
          title: Expected Duration S
        deduped:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Deduped
        rate_limited:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Rate Limited
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
      type: object
      required:
      - suburb
      title: ScrapeQueuedResponse
      description: 'Response shape for POST /rea-live/search.


        Note: `job_id` is OPTIONAL because the search_rea_live tool returns

        `existing_job_id` (no `job_id`) when a dedup hit occurs — same

        suburb scraped within the last 30 minutes reuses the prior job.

        Without making job_id optional, the dedup path 422s with

        "ValidationError: job_id Field required" — confirmed in prod

        2026-05-23. Callers should check `existing_job_id` when `job_id`

        is absent.'
    ScrapeRequest:
      properties:
        suburb:
          type: string
          maxLength: 80
          minLength: 2
          title: Suburb
          description: Suburb to scrape, e.g. 'Coorparoo' or 'Mooloolaba'.
        postcode:
          anyOf:
          - type: string
            pattern: ^\d{4}$
          - type: 'null'
          title: Postcode
          description: Optional postcode; auto-resolved from ci_properties if omitted.
        max_price:
          anyOf:
          - type: integer
            maximum: 50000000.0
            minimum: 10000.0
          - type: 'null'
          title: Max Price
          description: Optional max listing price in AUD.
        min_lot_m2:
          anyOf:
          - type: integer
            maximum: 200000.0
            minimum: 100.0
          - type: 'null'
          title: Min Lot M2
          description: Optional minimum lot area in m².
      type: object
      required:
      - suburb
      title: ScrapeRequest
      description: 'Inputs accepted by POST /rea-live/search.


        Mirrors search_rea_live''s tool input schema so the underlying

        function is called untouched.'
    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
    ScrapeResultResponse:
      properties:
        job_id:
          type: string
          title: Job Id
        status:
          type: string
          title: Status
        suburb:
          type: string
          title: Suburb
        queued_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Queued At
        started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started At
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
        duration_s:
          anyOf:
          - type: number
          - type: 'null'
          title: Duration S
        listings_found:
          anyOf:
          - type: integer
          - type: 'null'
          title: Listings Found
        listings:
          items:
            $ref: '#/components/schemas/ScrapeListing'
          type: array
          title: Listings
          default: []
        executor:
          anyOf:
          - type: string
          - type: 'null'
          title: Executor
        error_class:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Class
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
      type: object
      required:
      - job_id
      - status
      - suburb
      title: ScrapeResultResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key