openapi: 3.2.0
info:
  title: LiteLLM tool management API
  description: "Enterprise Edition \n\nProxy Server to call 100+ LLMs in the OpenAI format. [**Customize Swagger Docs**](https://docs.litellm.ai/docs/proxy/enterprise#swagger-docs---custom-routes--branding)\n\n\U0001F449 [```LiteLLM Admin Panel on /ui```](/ui). Create, Edit Keys with SSO. Having issues? Try [```Fallback Login```](/fallback/login)\n\n\U0001F4B8 [```LiteLLM Model Cost Map```](https://models.litellm.ai/).\n\n\U0001F50E [```LiteLLM Model Hub```](/ui/model_hub_table). See available models on the proxy. [**Docs**](https://docs.litellm.ai/docs/proxy/ai_hub)"
  version: 1.95.0
  x-operator: institution
  x-provenance:
    method: probed
    source: https://llmproxy.uva.nl/openapi.json
    retrieved: '2026-08-19'
    note: Document is generated by the LiteLLM proxy software the University of Amsterdam self-hosts; the deployment, the key issuance and the host (llmproxy.uva.nl, UvA Azure) are the institution's. servers[] added by API Evangelist because the served document omits it; nothing else altered.
servers:
- url: https://llmproxy.uva.nl
  description: University of Amsterdam / Amsterdam University of Applied Sciences shared AI gateway
tags:
- name: tool management
paths:
  /v1/tool/policy/options:
    get:
      tags:
      - tool management
      summary: Get Tool Policy Options
      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':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolPolicyOptionsResponse'
      security:
      - APIKeyHeader: []
  /v1/tool/list:
    get:
      tags:
      - tool management
      summary: List Tools
      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
      security:
      - APIKeyHeader: []
      parameters:
      - name: input_policy
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - trusted
            - untrusted
            - blocked
            type: string
          - type: 'null'
          title: Input Policy
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/tool/spend:
    get:
      tags:
      - tool management
      summary: Get Tool Spend
      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
      security:
      - APIKeyHeader: []
      parameters:
      - name: start_date
        in: query
        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 30 days ago)
      - name: end_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: YYYY-MM-DD (defaults to today)
          title: End Date
        description: YYYY-MM-DD (defaults to today)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolSpendResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/tool/{tool_name}/detail:
    get:
      tags:
      - tool management
      summary: Get Tool Detail
      description: Get a single tool with its policy overrides (for UI detail view).
      operationId: get_tool_detail_v1_tool__tool_name__detail_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: tool_name
        in: path
        required: true
        schema:
          type: string
          title: Tool Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/tool/{tool_name}/logs:
    get:
      tags:
      - tool management
      summary: Get Tool Usage Logs
      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
      security:
      - APIKeyHeader: []
      parameters:
      - name: tool_name
        in: path
        required: true
        schema:
          type: string
          title: Tool Name
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          title: Page Size
      - name: start_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: YYYY-MM-DD
          title: Start Date
        description: YYYY-MM-DD
      - name: end_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: YYYY-MM-DD
          title: End Date
        description: YYYY-MM-DD
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolUsageLogsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/tool/{tool_name}:
    get:
      tags:
      - tool management
      summary: Get Tool
      description: Get details for a single tool.
      operationId: get_tool_v1_tool__tool_name__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: tool_name
        in: path
        required: true
        schema:
          type: string
          title: Tool Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiteLLM_ToolTableRow'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/tool/policy:
    post:
      tags:
      - tool management
      summary: Update Tool Policy
      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':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolPolicyUpdateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /v1/tool/{tool_name}/overrides:
    delete:
      tags:
      - tool management
      summary: Delete Tool Policy Override
      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
      security:
      - APIKeyHeader: []
      parameters:
      - name: tool_name
        in: path
        required: true
        schema:
          type: string
          title: Tool Name
      - name: team_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Team ID of the override to remove
          title: Team Id
        description: Team ID of the override to remove
      - name: key_hash
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Key hash of the override to remove
          title: Key Hash
        description: Key hash of the override to remove
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    LiteLLM_ToolTableRow:
      properties:
        tool_id:
          type: string
          title: Tool Id
        tool_name:
          type: string
          title: Tool Name
        origin:
          anyOf:
          - type: string
          - type: 'null'
          title: Origin
        input_policy:
          type: string
          enum:
          - trusted
          - untrusted
          - blocked
          title: Input Policy
          default: untrusted
        output_policy:
          type: string
          enum:
          - trusted
          - untrusted
          title: Output Policy
          default: untrusted
        call_count:
          type: integer
          title: Call Count
          default: 0
        assignments:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Assignments
        key_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Hash
        team_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Team Id
        key_alias:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Alias
        user_agent:
          anyOf:
          - type: string
          - type: 'null'
          title: User Agent
        last_used_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Used At
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
        created_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Created By
        updated_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Updated By
      type: object
      required:
      - tool_id
      - tool_name
      title: LiteLLM_ToolTableRow
    ToolPolicyOption:
      properties:
        value:
          type: string
          title: Value
        label:
          type: string
          title: Label
        description:
          type: string
          title: Description
      type: object
      required:
      - value
      - label
      - description
      title: ToolPolicyOption
    ToolPolicyOverrideRow:
      properties:
        override_id:
          type: string
          title: Override Id
        tool_name:
          type: string
          title: Tool Name
        team_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Team Id
        key_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Hash
        input_policy:
          type: string
          enum:
          - trusted
          - untrusted
          - blocked
          title: Input Policy
          default: blocked
        key_alias:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Alias
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
      type: object
      required:
      - override_id
      - tool_name
      title: ToolPolicyOverrideRow
    ToolDetailResponse:
      properties:
        tool:
          $ref: '#/components/schemas/LiteLLM_ToolTableRow'
        overrides:
          items:
            $ref: '#/components/schemas/ToolPolicyOverrideRow'
          type: array
          title: Overrides
      type: object
      required:
      - tool
      title: ToolDetailResponse
    ToolUsageLogsResponse:
      properties:
        logs:
          items:
            $ref: '#/components/schemas/ToolUsageLogEntry'
          type: array
          title: Logs
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        page_size:
          type: integer
          title: Page Size
      type: object
      required:
      - logs
      - total
      - page
      - page_size
      title: ToolUsageLogsResponse
    ToolPolicyUpdateRequest:
      properties:
        tool_name:
          type: string
          title: Tool Name
        input_policy:
          anyOf:
          - type: string
            enum:
            - trusted
            - untrusted
            - blocked
          - type: 'null'
          title: Input Policy
        output_policy:
          anyOf:
          - type: string
            enum:
            - trusted
            - untrusted
          - type: 'null'
          title: Output Policy
        team_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Team Id
        key_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Hash
        key_alias:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Alias
      type: object
      required:
      - tool_name
      title: ToolPolicyUpdateRequest
    ToolListResponse:
      properties:
        tools:
          items:
            $ref: '#/components/schemas/LiteLLM_ToolTableRow'
          type: array
          title: Tools
        total:
          type: integer
          title: Total
      type: object
      required:
      - tools
      - total
      title: ToolListResponse
    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
    ToolPolicyUpdateResponse:
      properties:
        tool_name:
          type: string
          title: Tool Name
        input_policy:
          anyOf:
          - type: string
            enum:
            - trusted
            - untrusted
            - blocked
          - type: 'null'
          title: Input Policy
        output_policy:
          anyOf:
          - type: string
            enum:
            - trusted
            - untrusted
          - type: 'null'
          title: Output Policy
        updated:
          type: boolean
          title: Updated
        team_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Team Id
        key_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Hash
      type: object
      required:
      - tool_name
      - updated
      title: ToolPolicyUpdateResponse
    ToolUsageLogEntry:
      properties:
        id:
          type: string
          title: Id
        timestamp:
          type: string
          title: Timestamp
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
        spend:
          anyOf:
          - type: number
          - type: 'null'
          title: Spend
        total_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Tokens
        input_snippet:
          anyOf:
          - type: string
          - type: 'null'
          title: Input Snippet
      type: object
      required:
      - id
      - timestamp
      title: ToolUsageLogEntry
      description: One spend log row for a tool call (for UI "recent logs" table).
    ToolSpendEntry:
      properties:
        tool_name:
          type: string
          title: Tool Name
        spend:
          type: number
          title: Spend
          description: 'Attributed spend: a request that used several tools counts its full spend toward each of them'
          default: 0.0
        call_count:
          type: integer
          title: Call Count
          default: 0
        total_tokens:
          type: integer
          title: Total Tokens
          default: 0
      type: object
      required:
      - tool_name
      title: ToolSpendEntry
      description: Total spend attributed to one tool over the requested window.
    ToolPolicyOptionsResponse:
      properties:
        input_policies:
          items:
            $ref: '#/components/schemas/ToolPolicyOption'
          type: array
          title: Input Policies
        output_policies:
          items:
            $ref: '#/components/schemas/ToolPolicyOption'
          type: array
          title: Output Policies
      type: object
      required:
      - input_policies
      - output_policies
      title: ToolPolicyOptionsResponse
    ToolSpendDailyEntry:
      properties:
        date:
          type: string
          title: Date
        tool_name:
          type: string
          title: Tool Name
        spend:
          type: number
          title: Spend
          default: 0.0
        call_count:
          type: integer
          title: Call Count
          default: 0
      type: object
      required:
      - date
      - tool_name
      title: ToolSpendDailyEntry
      description: Spend attributed to one tool on one UTC day.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ToolSpendResponse:
      properties:
        by_tool:
          items:
            $ref: '#/components/schemas/ToolSpendEntry'
          type: array
          title: By Tool
        daily:
          items:
            $ref: '#/components/schemas/ToolSpendDailyEntry'
          type: array
          title: Daily
        start_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Start Date
        end_date:
          anyOf:
          - type: string
          - type: 'null'
          title: End Date
      type: object
      title: ToolSpendResponse
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: Bearer token
      in: header
      name: x-litellm-api-key