Casa Intelligence Agent API

openapi: 3.2.0
info:
  title: Casa Intelligence Engine Agent API
  description: Proprietary data ingestion, analysis, and prediction engine for Queensland property development intelligence.
  version: 2.0.0
tags:
- name: Agent
paths:
  /api/v1/agent/execute:
    post:
      tags:
      - Agent
      summary: Agent Execute
      description: 'Execute the AI agent with tool-use loop.


        Returns an SSE stream with events: thinking, tool_use, tool_result, message, done, error.


        Requires authentication (JWT or API key).

        Rate limited based on subscription tier.


        NOTE: Does NOT use Depends(get_db) — the agent loop can run for minutes

        (multiple Anthropic API calls). Holding a DB connection for that long

        exhausts the pool and blocks all other endpoints. Instead, short-lived

        sessions are created per tool execution inside the agent loop.'
      operationId: agent_execute_api_v1_agent_execute_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentExecuteRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/agent/proactive:
    post:
      tags:
      - Agent
      summary: Agent Proactive
      description: 'Quick proactive analysis for a property.


        Returns three insight fields: key_opportunity, watch_out, quick_take.

        Uses Haiku for fast response. Cached per property+user for 24h.


        Does NOT count against agent query quota.


        NOTE: Does NOT use Depends(get_db) — the function creates its own

        short-lived session for DB queries and releases it before calling

        the Anthropic API, avoiding connection pool exhaustion.'
      operationId: agent_proactive_api_v1_agent_proactive_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProactiveRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProactiveResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/agent/match-briefs:
    post:
      tags:
      - Agent
      summary: Agent Match Briefs
      description: 'Match a property against all active client briefs for the user''s org.


        Returns match scores and reasons for each brief.

        Buyer''s Agent segment feature.'
      operationId: agent_match_briefs_api_v1_agent_match_briefs_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MatchBriefsRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchBriefsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/agent/conversations:
    post:
      tags:
      - Agent
      summary: Save Conversation
      description: Save a chat conversation.
      operationId: save_conversation_api_v1_agent_conversations_post
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveConversationRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Agent
      summary: List Conversations
      description: List recent conversations, optionally filtered by property or suburb.
      operationId: list_conversations_api_v1_agent_conversations_get
      security:
      - HTTPBearer: []
      parameters:
      - name: property_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Property Id
      - name: suburb
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Suburb
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/agent/conversations/{conversation_id}:
    get:
      tags:
      - Agent
      summary: Get Conversation
      description: Get a specific conversation with full messages.
      operationId: get_conversation_api_v1_agent_conversations__conversation_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          title: Conversation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/agent/feed:
    get:
      tags:
      - Agent
      summary: Get Intelligence Feed
      description: 'Proactive intelligence feed for the Command Centre sidebar.


        Returns recent DA decisions in the user''s project LGAs,

        learning stats, and project reminders.'
      operationId: get_intelligence_feed_api_v1_agent_feed_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/v1/agent/confirm-action:
    post:
      tags:
      - Agent
      summary: Confirm Action
      description: 'Confirm or deny a pending AI action.


        The AI proposes write actions (create project, send email, etc.)

        and the frontend renders Approve/Deny buttons. This endpoint

        executes the action if approved.


        Actions are stored in the database (ci_pending_actions) so they

        persist across server restarts and don''t expire arbitrarily.

        They remain pending until the user approves or denies them.'
      operationId: confirm_action_api_v1_agent_confirm_action_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmActionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/agent/pending-actions:
    get:
      tags:
      - Agent
      summary: List Pending Actions
      description: List all pending actions for the current user.
      operationId: list_pending_actions_api_v1_agent_pending_actions_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
components:
  schemas:
    MatchBriefsRequest:
      properties:
        property_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Property Id
        address:
          type: string
          title: Address
      type: object
      required:
      - address
      title: MatchBriefsRequest
    ProactiveResponse:
      properties:
        key_opportunity:
          type: string
          title: Key Opportunity
        watch_out:
          type: string
          title: Watch Out
        quick_take:
          type: string
          title: Quick Take
      type: object
      required:
      - key_opportunity
      - watch_out
      - quick_take
      title: ProactiveResponse
    app__api__v1__agent__BriefMatchResult:
      properties:
        brief_id:
          type: string
          title: Brief Id
        client_name:
          type: string
          title: Client Name
        match_score:
          type: integer
          title: Match Score
        match_reasons:
          items:
            type: string
          type: array
          title: Match Reasons
        gaps:
          items:
            type: string
          type: array
          title: Gaps
      type: object
      required:
      - brief_id
      - client_name
      - match_score
      - match_reasons
      - gaps
      title: BriefMatchResult
    AgentExecuteRequest:
      properties:
        property_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Property Id
        address:
          anyOf:
          - type: string
          - type: 'null'
          title: Address
        message:
          type: string
          title: Message
        conversation_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Conversation Id
        intent:
          anyOf:
          - type: string
          - type: 'null'
          title: Intent
        context:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Context
        history:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: History
      type: object
      required:
      - message
      title: AgentExecuteRequest
    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
    ConfirmActionRequest:
      properties:
        action_id:
          type: string
          title: Action Id
        approved:
          type: boolean
          title: Approved
      type: object
      required:
      - action_id
      - approved
      title: ConfirmActionRequest
    SaveConversationRequest:
      properties:
        property_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Property Id
        property_address:
          anyOf:
          - type: string
          - type: 'null'
          title: Property Address
        suburb:
          anyOf:
          - type: string
          - type: 'null'
          title: Suburb
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        messages:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Messages
      type: object
      required:
      - messages
      title: SaveConversationRequest
    MatchBriefsResponse:
      properties:
        matches:
          items:
            $ref: '#/components/schemas/app__api__v1__agent__BriefMatchResult'
          type: array
          title: Matches
      type: object
      required:
      - matches
      title: MatchBriefsResponse
    ProactiveRequest:
      properties:
        property_id:
          type: string
          title: Property Id
        address:
          type: string
          title: Address
      type: object
      required:
      - property_id
      - address
      title: ProactiveRequest
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key