dialogbrain-com Tools API

openapi: 3.2.0
info:
  title: DialogBrain v2 API Gateway Tools API
  description: Clean refactored API gateway with minimal vertical slice
  version: 0.1.0
tags:
- name: Tools
paths:
  /api/tools/catalog:
    get:
      tags:
      - Tools
      summary: List available tools
      description: 'List all available tools based on the specified mode and filters.


        Returns a catalog of tools that can be executed in the current context.


        When ``background=true`` is set, each tool in the response gains three

        extra fields used by the per-agent Tools override UI:

        - ``default_visible``: whether the tool is in the default set for the

        given agent''s connected channels (``agent_id``) or, if no agent is

        specified, assuming all channels connected.

        - ``required_channel``: the channel literal the tool requires, or null.

        - ``schema_bytes``: cached byte cost of the tool''s OpenAI function

        schema — the UI multiplies this by the caller''s selection to estimate

        per-agent token cost.'
      operationId: list_tools_api_tools_catalog_get
      parameters:
      - name: mode
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ExecutionMode'
          default: draft
      - name: include_approval_required
        in: query
        required: false
        schema:
          type: boolean
          default: true
          title: Include Approval Required
      - name: category
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Search
      - name: planner_only
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Planner Only
      - name: background
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Background
      - name: include_hidden
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Hidden
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Tools Api Tools Catalog Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/tools/{tool_id}/schema:
    get:
      tags:
      - Tools
      summary: Get tool JSON schema
      description: 'Get the JSON schema for a specific tool.


        Returns the schema in OpenAI function calling format.'
      operationId: get_tool_schema_api_tools__tool_id__schema_get
      parameters:
      - name: tool_id
        in: path
        required: true
        schema:
          type: string
          title: Tool Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Tool Schema Api Tools  Tool Id  Schema Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/tools/{tool_id}/preview:
    post:
      tags:
      - Tools
      summary: Preview tool execution
      description: 'Preview what a tool will do without executing it.


        Returns a preview card and guard check results.'
      operationId: preview_tool_api_tools__tool_id__preview_post
      parameters:
      - name: tool_id
        in: path
        required: true
        schema:
          type: string
          title: Tool Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolPreviewRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Preview Tool Api Tools  Tool Id  Preview Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/tools/{tool_id}/execute:
    post:
      tags:
      - Tools
      summary: Execute a tool
      description: 'Execute a tool with the specified parameters.


        May return an approval required response if the tool needs approval.'
      operationId: execute_tool_api_tools__tool_id__execute_post
      parameters:
      - name: tool_id
        in: path
        required: true
        schema:
          type: string
          title: Tool Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolExecuteRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Execute Tool Api Tools  Tool Id  Execute Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/tools/{tool_id}/approve:
    post:
      tags:
      - Tools
      summary: Execute tool with approval
      description: 'Execute a tool that requires approval, with an approval token.


        Used after getting an approval_required response from /execute.'
      operationId: execute_with_approval_api_tools__tool_id__approve_post
      parameters:
      - name: tool_id
        in: path
        required: true
        schema:
          type: string
          title: Tool Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolApprovalRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Execute With Approval Api Tools  Tool Id  Approve Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/tools/categories:
    get:
      tags:
      - Tools
      summary: List tool categories
      description: List all available tool categories.
      operationId: list_categories_api_tools_categories_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response List Categories Api Tools Categories Get
  /api/tools/effects:
    get:
      tags:
      - Tools
      summary: List effect classes
      description: List all effect classes and their descriptions.
      operationId: list_effects_api_tools_effects_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response List Effects Api Tools Effects Get
  /api/tools/modes:
    get:
      tags:
      - Tools
      summary: List execution modes
      description: List all execution modes and their capabilities.
      operationId: list_modes_api_tools_modes_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response List Modes Api Tools Modes Get
  /api/tools/cache/stats:
    get:
      tags:
      - Tools
      summary: Get tool cache statistics
      description: Get statistics for the tool result cache.
      operationId: get_cache_stats_api_tools_cache_stats_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Get Cache Stats Api Tools Cache Stats Get
  /api/tools/cache/clear:
    post:
      tags:
      - Tools
      summary: Clear tool cache
      description: 'Clear the tool result cache.


        Args:

        tool_id: Optional tool ID to clear specific tool cache'
      operationId: clear_cache_api_tools_cache_clear_post
      parameters:
      - name: tool_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Tool Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Clear Cache Api Tools Cache Clear Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ToolApprovalRequest:
      properties:
        tool_id:
          type: string
          title: Tool Id
          description: ID of the tool to execute
        params:
          additionalProperties: true
          type: object
          title: Params
          description: Tool parameters
        approval_token:
          type: string
          title: Approval Token
          description: Token proving user approval
        mode:
          $ref: '#/components/schemas/ExecutionMode'
          description: Execution mode
          default: draft
        thread_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Thread Id
          description: Thread/channel ID for context
        request_id:
          type: string
          title: Request Id
          description: Request ID for idempotency
      type: object
      required:
      - tool_id
      - approval_token
      - request_id
      title: ToolApprovalRequest
      description: Request for executing a tool with approval.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ToolPreviewRequest:
      properties:
        tool_id:
          type: string
          title: Tool Id
          description: ID of the tool to preview
        params:
          additionalProperties: true
          type: object
          title: Params
          description: Tool parameters
        mode:
          $ref: '#/components/schemas/ExecutionMode'
          description: Execution mode for preview
          default: draft
        thread_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Thread Id
          description: Thread/channel ID for context
      type: object
      required:
      - tool_id
      title: ToolPreviewRequest
      description: Request for previewing tool execution.
    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
    ToolExecuteRequest:
      properties:
        tool_id:
          type: string
          title: Tool Id
          description: ID of the tool to execute
        params:
          additionalProperties: true
          type: object
          title: Params
          description: Tool parameters
        mode:
          $ref: '#/components/schemas/ExecutionMode'
          description: Execution mode
          default: draft
        skip_approval:
          type: boolean
          title: Skip Approval
          description: Skip approval requirement (requires auto mode)
          default: false
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
          description: Conversation session ID
        thread_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Thread Id
          description: Thread/channel ID for context
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Additional metadata
      type: object
      required:
      - tool_id
      title: ToolExecuteRequest
      description: Request for executing a tool.
    ExecutionMode:
      type: string
      enum:
      - draft
      - auto
      - supervised
      - autonomous
      - background_draft
      - post_approval
      - sandbox
      - voice
      title: ExecutionMode
      description: Execution modes for the AI agent.