APIClaw Tools API

openapi: 3.2.0
info:
  title: LiteLLM Tools API
  description: 'Proxy Server to call 100+ LLMs in the OpenAI format. **Customize Swagger Docs**


    👉 ```LiteLLM Admin Panel on /ui```. Create, Edit Keys with SSO. Having issues? Try ```Fallback Login```


    💸 ```LiteLLM Model Cost Map```.


    🔎 ```LiteLLM Model Hub```. See available models on the proxy. **Docs**'
  version: 1.102.1
tags:
- name: Tools
paths:
  /v1/tool/list:
    get:
      description: 'List all auto-discovered tools and their policies.


        Parameters:

        - input_policy: Optional filter — one of "trusted", "untrusted", "blocked"'
      operationId: list_tools_v1_tool_list_get
      parameters:
      - in: query
        name: input_policy
        required: false
        schema:
          anyOf:
          - enum:
            - trusted
            - untrusted
            - blocked
            type: string
          - type: 'null'
          title: Input Policy
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolListResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - APIKeyHeader: []
      summary: List Tools
      tags:
      - Tools
  /v1/tool/policy:
    post:
      description: 'Set the input_policy and/or output_policy for a tool (global), or block for a specific team/key (override).


        Parameters:

        - tool_name: str - The tool to update

        - input_policy: optional - "trusted" | "untrusted" | "blocked"

        - output_policy: optional - "trusted" | "untrusted"

        - team_id: optional - if set, create/update override for this team only

        - key_hash: optional - if set, create/update override for this key only'
      operationId: update_tool_policy_v1_tool_policy_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolPolicyUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolPolicyUpdateResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - APIKeyHeader: []
      summary: Update Tool Policy
      tags:
      - Tools
  /v1/tool/policy/options:
    get:
      description: 'Return the available input and output policy options with descriptions.

        Static data — no DB call.'
      operationId: get_tool_policy_options_v1_tool_policy_options_get
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolPolicyOptionsResponse'
          description: Successful Response
      security:
      - APIKeyHeader: []
      summary: Get Tool Policy Options
      tags:
      - Tools
  /v1/tool/spend:
    get:
      description: 'Spend attributed to each tool over a date range, for the Cost Optimization dashboard.


        Reads the ``LiteLLM_DailyToolSpend`` rollup, written at request time from invoked

        tools only (MCP tool calls and response tool_calls; declaring a tool without

        invoking it does not count). A request that invoked multiple tools counts its

        full spend toward each of them, so per-tool numbers are attributions and do not

        sum to a deduplicated total.


        ``by_tool`` is the top ``TOOL_SPEND_TOP_TOOLS`` tools by spend, aggregated in

        SQL, and ``daily`` covers only those tools, so the response is bounded by

        days x TOOL_SPEND_TOP_TOOLS regardless of the requested range or how many

        distinct tool names exist.'
      operationId: get_tool_spend_v1_tool_spend_get
      parameters:
      - description: YYYY-MM-DD (defaults to 30 days ago)
        in: query
        name: start_date
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: YYYY-MM-DD (defaults to 30 days ago)
          title: Start Date
      - description: YYYY-MM-DD (defaults to today)
        in: query
        name: end_date
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: YYYY-MM-DD (defaults to today)
          title: End Date
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolSpendResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - APIKeyHeader: []
      summary: Get Tool Spend
      tags:
      - Tools
  /v1/tool/{tool_name}:
    get:
      description: Get details for a single tool.
      operationId: get_tool_v1_tool__tool_name__get
      parameters:
      - in: path
        name: tool_name
        required: true
        schema:
          title: Tool Name
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiteLLM_ToolTableRow'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - APIKeyHeader: []
      summary: Get Tool
      tags:
      - Tools
  /v1/tool/{tool_name}/detail:
    get:
      description: Get a single tool with its policy overrides (for UI detail view).
      operationId: get_tool_detail_v1_tool__tool_name__detail_get
      parameters:
      - in: path
        name: tool_name
        required: true
        schema:
          title: Tool Name
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolDetailResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - APIKeyHeader: []
      summary: Get Tool Detail
      tags:
      - Tools
  /v1/tool/{tool_name}/logs:
    get:
      description: 'Return paginated spend logs for requests that invoked this tool (from SpendLogToolIndex).

        Declaring a tool in a request body without the model invoking it does not create an entry.'
      operationId: get_tool_usage_logs_v1_tool__tool_name__logs_get
      parameters:
      - in: path
        name: tool_name
        required: true
        schema:
          title: Tool Name
          type: string
      - in: query
        name: page
        required: false
        schema:
          default: 1
          minimum: 1
          title: Page
          type: integer
      - in: query
        name: page_size
        required: false
        schema:
          default: 50
          maximum: 100
          minimum: 1
          title: Page Size
          type: integer
      - description: YYYY-MM-DD
        in: query
        name: start_date
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: YYYY-MM-DD
          title: Start Date
      - description: YYYY-MM-DD
        in: query
        name: end_date
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: YYYY-MM-DD
          title: End Date
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolUsageLogsResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - APIKeyHeader: []
      summary: Get Tool Usage Logs
      tags:
      - Tools
  /v1/tool/{tool_name}/overrides:
    delete:
      description: 'Remove a policy override for a tool. Specify the override by team_id or key_hash

        (exactly one required).'
      operationId: delete_tool_policy_override_v1_tool__tool_name__overrides_delete
      parameters:
      - in: path
        name: tool_name
        required: true
        schema:
          title: Tool Name
          type: string
      - description: Team ID of the override to remove
        in: query
        name: team_id
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Team ID of the override to remove
          title: Team Id
      - description: Key hash of the override to remove
        in: query
        name: key_hash
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Key hash of the override to remove
          title: Key Hash
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - APIKeyHeader: []
      summary: Delete Tool Policy Override
      tags:
      - Tools
components:
  schemas:
    ToolUsageLogsResponse:
      properties:
        logs:
          items:
            $ref: '#/components/schemas/ToolUsageLogEntry'
          title: Logs
          type: array
        page:
          title: Page
          type: integer
        page_size:
          title: Page Size
          type: integer
        total:
          title: Total
          type: integer
      required:
      - logs
      - total
      - page
      - page_size
      title: ToolUsageLogsResponse
      type: object
    ToolListResponse:
      properties:
        tools:
          items:
            $ref: '#/components/schemas/LiteLLM_ToolTableRow'
          title: Tools
          type: array
        total:
          title: Total
          type: integer
      required:
      - tools
      - total
      title: ToolListResponse
      type: object
    ToolUsageLogEntry:
      description: One spend log row for a tool call (for UI "recent logs" table).
      properties:
        id:
          title: Id
          type: string
        input_snippet:
          anyOf:
          - type: string
          - type: 'null'
          title: Input Snippet
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
        spend:
          anyOf:
          - type: number
          - type: 'null'
          title: Spend
        timestamp:
          title: Timestamp
          type: string
        total_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Tokens
      required:
      - id
      - timestamp
      title: ToolUsageLogEntry
      type: object
    ToolSpendEntry:
      description: Total spend attributed to one tool over the requested window.
      properties:
        call_count:
          default: 0
          title: Call Count
          type: integer
        spend:
          default: 0.0
          description: 'Attributed spend: a request that used several tools counts its full spend toward each of them'
          title: Spend
          type: number
        tool_name:
          title: Tool Name
          type: string
        total_tokens:
          default: 0
          title: Total Tokens
          type: integer
      required:
      - tool_name
      title: ToolSpendEntry
      type: object
    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
    ToolPolicyOption:
      properties:
        description:
          title: Description
          type: string
        label:
          title: Label
          type: string
        value:
          title: Value
          type: string
      required:
      - value
      - label
      - description
      title: ToolPolicyOption
      type: object
    ToolDetailResponse:
      properties:
        overrides:
          items:
            $ref: '#/components/schemas/ToolPolicyOverrideRow'
          title: Overrides
          type: array
        tool:
          $ref: '#/components/schemas/LiteLLM_ToolTableRow'
      required:
      - tool
      title: ToolDetailResponse
      type: object
    LiteLLM_ToolTableRow:
      properties:
        assignments:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Assignments
        call_count:
          default: 0
          title: Call Count
          type: integer
        created_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Created At
        created_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Created By
        input_policy:
          default: untrusted
          enum:
          - trusted
          - untrusted
          - blocked
          title: Input Policy
          type: string
        key_alias:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Alias
        key_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Hash
        last_used_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Last Used At
        origin:
          anyOf:
          - type: string
          - type: 'null'
          title: Origin
        output_policy:
          default: untrusted
          enum:
          - trusted
          - untrusted
          title: Output Policy
          type: string
        team_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Team Id
        tool_id:
          title: Tool Id
          type: string
        tool_name:
          title: Tool Name
          type: string
        updated_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Updated At
        updated_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Updated By
        user_agent:
          anyOf:
          - type: string
          - type: 'null'
          title: User Agent
      required:
      - tool_id
      - tool_name
      title: LiteLLM_ToolTableRow
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ToolPolicyOptionsResponse:
      properties:
        input_policies:
          items:
            $ref: '#/components/schemas/ToolPolicyOption'
          title: Input Policies
          type: array
        output_policies:
          items:
            $ref: '#/components/schemas/ToolPolicyOption'
          title: Output Policies
          type: array
      required:
      - input_policies
      - output_policies
      title: ToolPolicyOptionsResponse
      type: object
    ToolPolicyUpdateResponse:
      properties:
        input_policy:
          anyOf:
          - enum:
            - trusted
            - untrusted
            - blocked
            type: string
          - type: 'null'
          title: Input Policy
        key_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Hash
        output_policy:
          anyOf:
          - enum:
            - trusted
            - untrusted
            type: string
          - type: 'null'
          title: Output Policy
        team_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Team Id
        tool_name:
          title: Tool Name
          type: string
        updated:
          title: Updated
          type: boolean
      required:
      - tool_name
      - updated
      title: ToolPolicyUpdateResponse
      type: object
    ToolPolicyUpdateRequest:
      properties:
        input_policy:
          anyOf:
          - enum:
            - trusted
            - untrusted
            - blocked
            type: string
          - type: 'null'
          title: Input Policy
        key_alias:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Alias
        key_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Hash
        output_policy:
          anyOf:
          - enum:
            - trusted
            - untrusted
            type: string
          - type: 'null'
          title: Output Policy
        team_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Team Id
        tool_name:
          title: Tool Name
          type: string
      required:
      - tool_name
      title: ToolPolicyUpdateRequest
      type: object
    ToolSpendResponse:
      properties:
        by_tool:
          items:
            $ref: '#/components/schemas/ToolSpendEntry'
          title: By Tool
          type: array
        daily:
          items:
            $ref: '#/components/schemas/ToolSpendDailyEntry'
          title: Daily
          type: array
        end_date:
          anyOf:
          - type: string
          - type: 'null'
          title: End Date
        start_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Start Date
      title: ToolSpendResponse
      type: object
    ToolPolicyOverrideRow:
      properties:
        created_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Created At
        input_policy:
          default: blocked
          enum:
          - trusted
          - untrusted
          - blocked
          title: Input Policy
          type: string
        key_alias:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Alias
        key_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Hash
        override_id:
          title: Override Id
          type: string
        team_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Team Id
        tool_name:
          title: Tool Name
          type: string
        updated_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Updated At
      required:
      - override_id
      - tool_name
      title: ToolPolicyOverrideRow
      type: object
    ToolSpendDailyEntry:
      description: Spend attributed to one tool on one UTC day.
      properties:
        call_count:
          default: 0
          title: Call Count
          type: integer
        date:
          title: Date
          type: string
        spend:
          default: 0.0
          title: Spend
          type: number
        tool_name:
          title: Tool Name
          type: string
      required:
      - date
      - tool_name
      title: ToolSpendDailyEntry
      type: object
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: Bearer token
      in: header
      name: x-litellm-api-key