dialogbrain-com Agent API

openapi: 3.2.0
info:
  title: DialogBrain v2 API Gateway Agent API
  description: Clean refactored API gateway with minimal vertical slice
  version: 0.1.0
tags:
- name: Agent
paths:
  /ai/stop:
    post:
      tags:
      - Agent
      summary: Stop
      description: 'Stop the caller''s run in this AI-panel session before its next step.


        The run ends with what it has; a step already running finishes first.'
      operationId: stop_ai_stop_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StopRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ai/query:
    post:
      tags:
      - Agent
      summary: Query
      description: 'AI query endpoint using NEW Planner/Executor workflow.


        New Plan-First Workflow (Phases 1 & 2):

        1. Create execution plan from query

        2. Return plan for user approval (via WebSocket)

        3. Execute plan after approval

        4. Stream progress via WebSocket


        This replaces the old AIService.stream_with_tools() approach.


        SECURITY: user_id is extracted from JWT token (cannot be spoofed).


        Args:

        request: Query request

        user: Current user (from JWT)

        db: Database session


        Returns:

        Plan details and approval status'
      operationId: query_ai_query_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/src__api__agent__QueryRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ai/approvals/pending:
    get:
      tags:
      - Agent
      summary: Get Pending Approvals
      description: 'Pending tool approvals for the caller — the HTTP fallback for lost

        `approval_required` WS events (fire-once pub/sub, no replay). The panel

        calls this on mount/reconnect and restores actionable Approve/Reject

        cards; responses still flow through the normal approval_response path.'
      operationId: get_pending_approvals_ai_approvals_pending_get
      parameters:
      - name: session_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ai/sessions:
    post:
      tags:
      - Agent
      summary: Get Sessions
      description: Get list of AI panel sessions from the unified thread table.
      operationId: get_sessions_ai_sessions_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetSessionsRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ai/messages:
    post:
      tags:
      - Agent
      summary: Get Messages
      description: Load AI panel messages for a session from the unified message table.
      operationId: get_messages_ai_messages_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetMessagesRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMessagesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      deprecated: true
  /ai/execute-action:
    post:
      tags:
      - Agent
      summary: Execute Action
      description: 'Execute approved action with idempotency.


        Pipeline:

        1. Check idempotency (request_id)

        2. Verify confirmation

        3. Execute action (send message via Telegram MCP)

        4. Return execution result


        SECURITY: user_id is extracted from JWT token (cannot be spoofed).


        Args:

        request: Action execution request

        user: Current user (from JWT)


        Returns:

        Execution result'
      operationId: execute_action_ai_execute_action_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteActionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecuteActionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ai/generate-action:
    post:
      tags:
      - Agent
      summary: Generate Action
      description: 'Generate draft action with RAG search and guard checks.


        Pipeline:

        1. rag.search(strict) - Search for relevant evidence

        2. guard.outbound.check - Safety checks

        3. Return DraftCard preview


        SECURITY: user_id is extracted from JWT token (cannot be spoofed).


        Args:

        request: Action generation request

        user: Current user (from JWT)


        Returns:

        DraftCard with preview, evidence, and guard results'
      operationId: generate_action_ai_generate_action_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateActionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DraftCard'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ai/metrics/tools:
    get:
      tags:
      - Agent
      summary: Get Tool Metrics
      description: 'Get tool usage metrics.


        Returns statistics about tool usage including:

        - Call counts per tool

        - Success/failure rates

        - Average execution times

        - Most used tools


        Requires authentication.'
      operationId: get_tool_metrics_ai_metrics_tools_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /ai/timeline:
    post:
      tags:
      - Agent
      summary: Get Timeline
      description: 'Load full timeline for a session.


        Returns all timeline events including:

        - Messages (user/assistant)

        - Tool executions with parameters and results

        - Plan summaries

        - User prompts


        This enables Cursor-like session restoration where the full

        conversation context is restored after page refresh.


        SECURITY: Verifies user owns the session.


        Args:

        request: Request with session_id and pagination

        user: Current user (from JWT)


        Returns:

        List of timeline events with pagination'
      operationId: get_timeline_ai_timeline_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetTimelineRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTimelineResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ai/session-memory/{session_id}:
    get:
      tags:
      - Agent
      summary: Get Session Memory
      description: 'Get Session Memory contents for debugging.


        Returns the current SessionMemory state including:

        - contact_bindings: Learned contact aliases (e.g., "жена" → thread_id)

        - last_target_aliases: Recent target names

        - artifacts: Found files/links during session

        - focus: Current thread context

        - current_thread: Active thread details


        This is useful for debugging AI Agent context awareness.


        SECURITY: Verifies user owns the session.


        Args:

        session_id: Session ID to get memory for

        user: Current user (from JWT)


        Returns:

        SessionMemory contents as JSON'
      operationId: get_session_memory_ai_session_memory__session_id__get
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ai/thread-summary/{thread_id}:
    get:
      tags:
      - Agent
      summary: Get Thread Summary
      description: 'Get thread summary, optionally generating if not exists.


        Args:

        thread_id: Thread ID to get summary for

        generate: If True, generate summary if not exists or stale

        force_refresh: If True, regenerate even if exists (requires generate=True)


        This endpoint returns the cached thread summary for context compression.

        Summaries include communication style analysis and role detection.'
      operationId: get_thread_summary_ai_thread_summary__thread_id__get
      parameters:
      - name: thread_id
        in: path
        required: true
        schema:
          type: integer
          title: Thread Id
      - name: generate
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Generate
      - name: force_refresh
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Force Refresh
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreadSummaryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ExecuteActionRequest:
      properties:
        action_id:
          type: string
          title: Action Id
        confirm:
          type: boolean
          title: Confirm
        request_id:
          type: string
          title: Request Id
        edited_content:
          anyOf:
          - type: string
          - type: 'null'
          title: Edited Content
      type: object
      required:
      - action_id
      - confirm
      - request_id
      title: ExecuteActionRequest
      description: Request to execute action.
    StopRequest:
      properties:
        session_id:
          type: string
          title: Session Id
      type: object
      required:
      - session_id
      title: StopRequest
    GenerateActionRequest:
      properties:
        thread_id:
          type: string
          title: Thread Id
        messages:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Messages
        goal:
          anyOf:
          - type: string
          - type: 'null'
          title: Goal
        instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Instructions
        strict_rag:
          type: boolean
          title: Strict Rag
          default: true
        channel:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel
        account_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Account Id
        recipient_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Recipient Name
      type: object
      required:
      - thread_id
      - messages
      title: GenerateActionRequest
      description: Request to generate action draft.
    GetSessionsRequest:
      properties:
        limit:
          type: integer
          title: Limit
          default: 50
        include_archived:
          type: boolean
          title: Include Archived
          default: false
      type: object
      title: GetSessionsRequest
      description: Request to load session list.
    DraftPreview:
      properties:
        title:
          type: string
          title: Title
        content:
          type: string
          title: Content
        recipients:
          items:
            type: string
          type: array
          title: Recipients
        evidence_used:
          type: boolean
          title: Evidence Used
          default: false
        evidence_count:
          type: integer
          title: Evidence Count
          default: 0
      type: object
      required:
      - title
      - content
      - recipients
      title: DraftPreview
      description: Draft message preview.
    GetMessagesResponse:
      properties:
        messages:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Messages
        total:
          type: integer
          title: Total
        has_more:
          type: boolean
          title: Has More
      type: object
      required:
      - messages
      - total
      - has_more
      title: GetMessagesResponse
      description: Response with session messages.
    GetTimelineRequest:
      properties:
        session_id:
          type: string
          title: Session Id
        limit:
          type: integer
          title: Limit
          default: 200
        offset:
          type: integer
          title: Offset
          default: 0
        event_types:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Event Types
        newest:
          anyOf:
          - type: integer
            maximum: 100.0
            minimum: 1.0
          - type: 'null'
          title: Newest
      type: object
      required:
      - session_id
      title: GetTimelineRequest
      description: Request to load session timeline.
    GetTimelineResponse:
      properties:
        events:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Events
        total:
          type: integer
          title: Total
        has_more:
          type: boolean
          title: Has More
      type: object
      required:
      - events
      - total
      - has_more
      title: GetTimelineResponse
      description: Response with session timeline events.
    DraftCard:
      properties:
        action_id:
          type: string
          title: Action Id
        thread_id:
          type: string
          title: Thread Id
        preview:
          $ref: '#/components/schemas/DraftPreview'
        evidence:
          items:
            $ref: '#/components/schemas/RAGEvidence'
          type: array
          title: Evidence
        guard:
          $ref: '#/components/schemas/GuardCheck'
        created_at:
          type: string
          format: date-time
          title: Created At
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
      type: object
      required:
      - action_id
      - thread_id
      - preview
      - guard
      title: DraftCard
      description: Complete draft card with preview, evidence, and guard checks.
    QueryResponse:
      properties:
        response:
          type: string
          title: Response
        actions:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Actions
        error:
          type: boolean
          title: Error
          default: false
        trace_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Trace Id
      type: object
      required:
      - response
      title: QueryResponse
      description: Response from AI agent query.
    GuardCheck:
      properties:
        status:
          $ref: '#/components/schemas/GuardStatus'
        issues:
          items:
            $ref: '#/components/schemas/GuardIssue'
          type: array
          title: Issues
        analysis:
          anyOf:
          - type: string
          - type: 'null'
          title: Analysis
        timestamp:
          type: string
          format: date-time
          title: Timestamp
      type: object
      required:
      - status
      title: GuardCheck
      description: Guard check result.
    GuardStatus:
      type: string
      enum:
      - pass
      - warning
      - block
      title: GuardStatus
      description: Guard check status.
    ExecuteActionResponse:
      properties:
        action_id:
          type: string
          title: Action Id
        status:
          type: string
          title: Status
        message_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Message Id
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        executed_at:
          type: string
          format: date-time
          title: Executed At
      type: object
      required:
      - action_id
      - status
      title: ExecuteActionResponse
      description: Response from action execution.
    src__api__agent__QueryRequest:
      properties:
        query:
          type: string
          title: Query
        session_id:
          type: string
          title: Session Id
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          default: gpt-4o
        context:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Context
        use_rag:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Use Rag
          default: true
      type: object
      required:
      - query
      - session_id
      title: QueryRequest
      description: Request for simple query to AI agent.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ThreadSummaryResponse:
      properties:
        thread_id:
          type: integer
          title: Thread Id
        summary_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Summary Text
        message_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Message Count
        last_summary_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Summary At
        model_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Name
        tokens_used:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tokens Used
        exists:
          type: boolean
          title: Exists
          default: false
      type: object
      required:
      - thread_id
      title: ThreadSummaryResponse
      description: Response model for thread summary endpoint.
    GetMessagesRequest:
      properties:
        session_id:
          type: string
          title: Session Id
        limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Limit
          default: 50
        offset:
          type: integer
          title: Offset
          default: 0
      type: object
      required:
      - session_id
      title: GetMessagesRequest
      description: Request to load session messages.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    GuardIssue:
      properties:
        type:
          type: string
          title: Type
        severity:
          type: string
          title: Severity
        description:
          type: string
          title: Description
        suggestion:
          anyOf:
          - type: string
          - type: 'null'
          title: Suggestion
      type: object
      required:
      - type
      - severity
      - description
      title: GuardIssue
      description: Individual guard issue detected.
    RAGEvidence:
      properties:
        text:
          type: string
          title: Text
        source_desc:
          type: string
          title: Source Desc
        relevance:
          type: number
          title: Relevance
        source_type:
          type: string
          title: Source Type
        uri:
          anyOf:
          - type: string
          - type: 'null'
          title: Uri
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        chunk_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Chunk Id
      type: object
      required:
      - text
      - source_desc
      - relevance
      - source_type
      title: RAGEvidence
      description: RAG search evidence.