POST /tools/{name}/test
Test a tool
Calls a tool and hands back what it answered. Supply conversationId to use a real conversation and its stored visitor; it must belong to this workspace and cannot be combined with as. Explicit refusals (known: false, ok: false, allowed: false, or blocked/unknown outcomes) return ok: false even when the endpoint returns HTTP 200. For checking a new install, where nobody has written in yet and there is no conversation to run against. Nothing lands in the inbox: no approval row, no thread, no message. It reaches the real endpoint, signed the way the agent signs, so test a low risk tool rather than a refund. Without as, the tool sees a visitor it cannot identify, which is how to check that an account tool refuses instead of guessing.
Part of Tool approvals.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The tool's name, as its manifest declares it. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
input | object | No | |
as | string | No | One of your own customer ids, the same value you sign into the widget. It arrives as context.visitor.externalId. Cannot be combined with conversationId. |
conversationId | string | No | A conversation in this workspace. Uses its stored visitor identity without adding a message or approval. |
Responses
| Status | Description |
|---|---|
200 | What the tool answered, whether or not it worked. |
400 | The request is malformed, and the message names the field. |
401 | The bearer token is missing, revoked, or expired. |
404 | Not one of yours, or not there at all. |
429 | Too many requests. Wait the seconds in Retry-After. Limits depend on the plan. See rate limits. |
200 body
| Field | Type | Required | Description |
|---|---|---|---|
ok | boolean | No | |
result | any | No | The tool's return value as JSON. Null when the call failed. |
error | any | No | Why it failed, in the words the agent would have read. |
risk | "low" | "medium" | "reviewed" | "high" | No | |
conversationId | string | No | The supplied conversation id, or a synthetic id prefixed test_ when none was supplied. |
Example request
curl -X POST https://api.median.sh/v1/tools/orderStatus/test \
-H "Authorization: Bearer $BEARER_AUTH" \
-H "content-type: application/json" \
-d '{"input":{"orderNumber":"ORD-1042"},"as":"user_123"}'