Casa Intelligence Events API

openapi: 3.2.0
info:
  title: Casa Intelligence Engine Events API
  description: Proprietary data ingestion, analysis, and prediction engine for Queensland property development intelligence.
  version: 2.0.0
tags:
- name: Events
paths:
  /api/v1/events:
    post:
      tags:
      - Events
      summary: Ingest Events
      description: 'Batch ingest events from extension or dashboard.


        Low-latency: batch-inserts to ci_events with minimal processing.

        Capped at 100 events per request.'
      operationId: ingest_events_api_v1_events_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventsBatchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /api/v1/events/website:
    post:
      tags:
      - Events
      summary: Ingest Website Event
      description: 'Ingest a single funnel event from the public website (no API key).


        ga_client_id is stored in anonymous_id (the canonical funnel join key) AND

        mirrored into metadata; free_check_id lives in metadata so the daily check

        can join events back to ci_free_checks rows.'
      operationId: ingest_website_event_api_v1_events_website_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebsiteEventRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebsiteEventResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    EventsBatchRequest:
      properties:
        events:
          items:
            $ref: '#/components/schemas/EventItem'
          type: array
          maxItems: 100
          minItems: 1
          title: Events
        anonymous_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Anonymous Id
          description: Extension installation ID for anonymous tracking
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
          description: Groups events into sessions
      type: object
      required:
      - events
      title: EventsBatchRequest
      description: Batch of events from extension or dashboard.
    WebsiteEventResponse:
      properties:
        ok:
          type: boolean
          title: Ok
          default: true
      type: object
      title: WebsiteEventResponse
      description: Response for website event ingestion.
    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
    EventsResponse:
      properties:
        status:
          type: string
          title: Status
          default: ok
        ingested:
          type: integer
          title: Ingested
          default: 0
      type: object
      title: EventsResponse
      description: Response from event ingestion.
    WebsiteEventRequest:
      properties:
        event_type:
          type: string
          maxLength: 64
          title: Event Type
        free_check_id:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Free Check Id
        ga_client_id:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Ga Client Id
        session_id:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Session Id
        address:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Address
        variant:
          anyOf:
          - type: string
            maxLength: 32
          - type: 'null'
          title: Variant
        dev_type:
          anyOf:
          - type: string
            maxLength: 32
          - type: 'null'
          title: Dev Type
        page:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Page
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Extra event-specific data (size-capped server-side)
      type: object
      required:
      - event_type
      title: WebsiteEventRequest
      description: 'A single funnel event from the public website (no API key).


        event_type must be on the server-side allow-list (see

        app/api/v1/events.py WEBSITE_EVENT_CATEGORIES) — this is analytics

        ingestion, not a general write endpoint. ga_client_id is the canonical

        funnel join key (DATA-CLARITY-AUDIT.md §5); free_check_id links the event

        to its originating ci_free_checks row.'
    EventItem:
      properties:
        event_type:
          type: string
          title: Event Type
          description: Event type, e.g. 'property_view', 'ai_question'
        event_category:
          type: string
          title: Event Category
          description: 'Category: ''engagement'', ''conversion'', ''feature_use'', ''navigation'''
          default: engagement
        property_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Property Id
          description: Property UUID if applicable
        source:
          type: string
          title: Source
          description: 'Source: ''extension'', ''dashboard'', ''api'''
          default: unknown
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Event-specific data
      type: object
      required:
      - event_type
      title: EventItem
      description: A single trackable event.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key