---
title: "Send a real test request for a tool definition that is not saved yet"
method: POST
path: "/v1/tools/test"
---

# Send a real test request for a tool definition that is not saved yet

`POST /v1/tools/test`

## Request

- Base URL: `https://volai.cz`
- URL: `https://volai.cz/v1/tools/test`
- Auth: HTTP bearer

Sends a REAL request per the definition you send and returns what came back - the tool is NOT saved (unlike `POST /v1/tools`, `label`/`description` are optional here). Handy for trying an address before saving it as an agent tool. `timeoutSecs` is only validated here (5 to 30) - a test always waits a fixed 10 seconds instead, so you don't sit through a full runtime timeout; it's the value the tool would use at runtime once saved. Shares a rate limit with `POST /v1/tools/{id}/test` below - 10 attempts per minute per account combined.

## Request body

- object
  - `label` string: Display name of the webhook tool, also used to derive its name for the agent. Reserved call-control names are not allowed.
  - `description` string: Tell the agent when to call this tool and what it does.
  - `url` string, required: Public HTTPS endpoint receiving the tool request. Local/private addresses are rejected; the endpoint must respond within timeoutSecs.
  - `method` string, required: HTTP request method: GET puts parameters in the query string, POST sends JSON. Case-insensitive GET or POST only.
  - `headers` object: Complete map of custom HTTP headers; {} clears them on PATCH. Values are secrets and returned redacted. Header names are case-insensitive and must be unique. host, content-length, x-conversation-id and x-caller-id are reserved.
  - `params` object[]: Complete parameter list. [] removes all parameters on PATCH. Names must be unique.
    - `name` string, required: Name sent to the endpoint: letter or underscore first, then letters, digits or underscores.
    - `type` 'string' | 'number' | 'boolean', required: JSON value type sent to the endpoint.
    - `source` 'llm' | 'caller_number' | 'called_number' | 'constant', required: llm asks the agent to supply the value; caller_number and called_number use call metadata; constant uses constantValue.
    - `description` string: Instructions for an llm-sourced parameter; required for source llm. Explain how to obtain the value from the conversation.
    - `constantValue` string: Fixed text value required for source constant; omit for other sources.
    - `required` boolean: For source llm, whether the parameter must be supplied. Defaults to false.
  - `timeoutSecs` integer: Maximum wait for the endpoint's response during a call, in whole seconds. Defaults to 20.

## Response `200`

Test result

- object
  - `status` number, required
  - `durationMs` number, required
  - `body` string, required
  - `note` string, nullable, required

## Other responses

- `400`: Error codes: validation (request), invalid_tool_url (request), private_address (request), invalid_tool_params (request), invalid_tool_headers (request).
- `401`: Error codes: unauthorized (request).
- `403`: Error codes: account_suspended (account).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service).

---

[API](https://skmtc.dev/volai/apis/volai-rest-api.md) · [All operations](https://skmtc.dev/volai/apis/volai-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volai/apis/volai-rest-api/revisions/12029b05e2fa?raw)