Casa Intelligence Status API

openapi: 3.2.0
info:
  title: Casa Intelligence Engine Status API
  description: Proprietary data ingestion, analysis, and prediction engine for Queensland property development intelligence.
  version: 2.0.0
tags:
- name: Status
paths:
  /engine/status:
    get:
      tags:
      - Status
      summary: Get Status
      description: 'Health check and status overview. No auth required.

        Returns database connectivity, per-source stats, and record counts.'
      operationId: get_status_engine_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
  /engine/health:
    get:
      tags:
      - Status
      summary: Health Check
      description: Simple health check for load balancers and monitoring.
      operationId: health_check_engine_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /engine/db-check:
    get:
      tags:
      - Status
      summary: Db Diagnostic
      description: 'Diagnostic: shows exact DB connection error if any.'
      operationId: db_diagnostic_engine_db_check_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /engine/metrics:
    get:
      tags:
      - Status
      summary: Metrics
      description: 'Lightweight pool + connection metrics for ops dashboards.


        Returns SQLAlchemy pool stats (per-worker view) plus pg_stat_activity

        summary (cluster-wide view). Used by the casa-daily ops dashboard

        and external monitors to detect pool saturation or zombie buildup

        before users feel it.


        Auth: relies on Railway''s private network — endpoint is registered

        behind the existing /engine prefix. If exposed publicly later, add

        X-API-Key gating like the v1 endpoints.


        Costs ~5ms — safe to poll every 10-30s.'
      operationId: metrics_engine_metrics_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  schemas:
    StatusResponse:
      properties:
        engine:
          type: string
          title: Engine
        version:
          type: string
          title: Version
        status:
          type: string
          title: Status
        database_connected:
          type: boolean
          title: Database Connected
        sources:
          items:
            $ref: '#/components/schemas/SourceStatus'
          type: array
          title: Sources
        total_da_records:
          type: integer
          title: Total Da Records
        total_planning_rules:
          type: integer
          title: Total Planning Rules
        uptime_info:
          anyOf:
          - type: string
          - type: 'null'
          title: Uptime Info
      type: object
      required:
      - engine
      - version
      - status
      - database_connected
      - sources
      - total_da_records
      - total_planning_rules
      title: StatusResponse
      description: Response from the status endpoint.
    IngestionRunResponse:
      properties:
        id:
          type: string
          title: Id
        source:
          type: string
          title: Source
        status:
          type: string
          title: Status
        records_fetched:
          type: integer
          title: Records Fetched
        records_new:
          type: integer
          title: Records New
        records_updated:
          type: integer
          title: Records Updated
        records_failed:
          type: integer
          title: Records Failed
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
      type: object
      required:
      - id
      - source
      - status
      - records_fetched
      - records_new
      - records_updated
      - records_failed
      title: IngestionRunResponse
      description: Representation of an ingestion run for the status endpoint.
    SourceStatus:
      properties:
        source:
          type: string
          title: Source
        last_run:
          anyOf:
          - $ref: '#/components/schemas/IngestionRunResponse'
          - type: 'null'
        total_records:
          type: integer
          title: Total Records
      type: object
      required:
      - source
      - total_records
      title: SourceStatus
      description: Status of a single ingestion source.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key