> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agents.labs.bandwidth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Test an HTTP tool

> Execute an HTTP API tool with supplied arguments.

> [!WARNING]
>
> Testing sends a real request to the configured destination and can change data in that service.

Requires Editor, Admin, or Owner, plus Admin or Owner for tools with stored credentials, headers, or preset values. Only HTTP API tools support this operation; other types return `400`. Supply `arguments` matching the tool parameters. Inspect the response success/error fields: an HTTP `200` response does not by itself mean the downstream request succeeded.


## OpenAPI

````yaml POST /api/v1/tools/{tool_uuid}/test
openapi: 3.1.0
info:
  title: Bandwidth Agent Builder API
  version: v1
  description: >-
    Manage agents, place calls, and retrieve conversation results in your
    workspace.
servers:
  - url: https://agents.labs.bandwidth.com
    description: Workspace API
security: []
paths:
  /api/v1/tools/{tool_uuid}/test:
    post:
      tags:
        - tools
      summary: Test an HTTP tool
      description: >-
        **Authorization:** Requires an Editor, Admin, or Owner role in the
        requested workspace.


        Execute an HTTP API tool with supplied arguments.
      operationId: test_tool_endpoint_api_v1_tools__tool_uuid__test_post
      parameters:
        - in: path
          name: tool_uuid
          required: true
          schema:
            title: Tool Uuid
            type: string
        - description: >-
            Required with X-BW-LABS-AGENTS-API-KEY: the positive local workspace
            ID to access. The key owner must be a current member. Missing or
            invalid IDs return 400; non-member workspaces return 403. Not
            required for bearer authentication, which uses the user's selected
            workspace.
          in: header
          name: X-VOAI-ORGANIZATION-ID
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Required with X-BW-LABS-AGENTS-API-KEY: the positive local
              workspace ID to access. The key owner must be a current member.
              Missing or invalid IDs return 400; non-member workspaces return
              403. Not required for bearer authentication, which uses the user's
              selected workspace.
            title: X-Voai-Organization-Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestToolRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestToolResponse'
          description: Successful Response
        '400':
          description: Invalid request or missing/invalid workspace header with an API key.
        '401':
          description: Missing, invalid, or expired credential.
        '403':
          description: >-
            The account lacks access to the workspace, resource, or required
            role.
        '404':
          description: Not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - LabsAuth: []
        - LabsApiKey: []
components:
  schemas:
    TestToolRequest:
      properties:
        arguments:
          additionalProperties: true
          title: Arguments
          type: object
      title: TestToolRequest
      type: object
    TestToolResponse:
      properties:
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        latency_ms:
          title: Latency Ms
          type: number
        status:
          title: Status
          type: string
        status_code:
          anyOf:
            - type: integer
            - type: 'null'
          title: Status Code
      required:
        - status
        - latency_ms
      title: TestToolResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
  securitySchemes:
    LabsAuth:
      description: >-
        Bandwidth Labs OAuth access token. Uses the user's selected workspace;
        the workspace header is not required. Do not also send an API key.
        Bearer-only operations may additionally require the Labs `super_user`
        role.
      scheme: bearer
      type: http
    LabsApiKey:
      description: >-
        Bandwidth Labs API key. Also send `X-VOAI-ORGANIZATION-ID` with a
        positive local workspace ID belonging to the key owner. Access follows
        the owner's current workspace role. Do not also send a bearer token. API
        keys cannot access bearer-only or Labs `super_user` operations.
      in: header
      name: X-BW-LABS-AGENTS-API-KEY
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.