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.

POST/tools/{name}/test

Authorization

AuthorizationBearer token · headerrequired

`MEDIAN_KEY` from Settings under API, or an MCP OAuth access token. A key acts as the organization; a token acts as the person who approved it.

Path parameters

namestringrequired

The tool's name, as its manifest declares it.

Request body

application/json

inputobject

asstring

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.

conversationIdstring

A conversation in this workspace. Uses its stored visitor identity without adding a message or approval.

Responses

200What the tool answered, whether or not it worked.

okboolean

resultstring | null

The tool's return value as JSON. Null when the call failed.

errorstring | null

Why it failed, in the words the agent would have read.

riskstring

Allowed:lowmediumreviewedhigh

conversationIdstring

The supplied conversation id, or a synthetic id prefixed test_ when none was supplied.

400The request is malformed, and the message names the field.

errorobject

Show properties

codestring

messagestring

401The bearer token is missing, revoked, or expired.

errorobject

Show properties

codestring

messagestring

404Not one of yours, or not there at all.

errorobject

Show properties

codestring

messagestring

429Too many requests. Wait the seconds in `Retry-After`. Limits depend on the plan. See [rate limits](/api/errors-and-limits#rate-limits).

errorobject

Show properties

codestring

messagestring

Request

curl -X POST "https://api.median.sh/v1/tools/orderStatus/test" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "orderNumber": "ORD-1042"
  },
  "as": "user_123"
}'

const response = await fetch("https://api.median.sh/v1/tools/orderStatus/test", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "input": {
    "orderNumber": "ORD-1042"
  },
  "as": "user_123"
})
});

Response

{
  "ok": true,
  "result": "string",
  "error": "string",
  "risk": "low",
  "conversationId": "string"
}