Skip to content
Median
Esc
↑↓navigate↵open⌘Jpreview

Run one tool, or answer diagnostics

A tool call from one conversation, or a diagnostics request when a report is filed.

Tool calls. Answer 200 with { result } when the tool ran. Answer 200 with an execution_failed error when the tool itself threw. The agent reads your message and is told not to retry. Keep other status codes for transport and config problems. On a 400 with code invalid_input the agent reads your message and is told to fix its input. On any other non-2xx answer the agent is told the tool is not answering, and your message is not passed to it.

Median sends each call once and does not retry it. The agent reads the first 4,000 characters of the result.

Diagnostics. The body is { "op": "diagnostics" }. Answer 200 with { result }, or 200 with diagnostics_unsupported when you collect nothing. Median waits 8 seconds and keeps the first 2,000 characters. An unknown op answers 400 unknown_op.

POST/
Authorization
median-signatureAPI key · headerrequired
`t=<ms>,v1=<hex>`, where `v1` is the HMAC SHA-256 of `${t}.${body}` under the tool signing secret derived from `MEDIAN_KEY`. Compare in constant time and refuse timestamps more than five minutes from your clock.
Request body
requiredapplication/json
One of:
ToolCall
toolstringrequired
The name from the manifest.
toolCallIdstringrequired
Unique per call. Use it as an idempotency key. `call_` and 32 hex characters when the agent called the tool, the approval request's id for approved and teammate-run calls, and `test_` and a UUID for `median tools test`. Treat it as opaque.
inputobjectrequired
The arguments. The agent is held to the tool's input schema, and `median()` validates them again.
contextobjectrequired
Show properties
conversationIdstringrequired
The conversation the call came from. For `median tools test` without `--conversation`, the same `test_` value as `toolCallId`.
riskRiskrequired
`low` runs when the agent calls it. `medium` runs when called, and the agent is told to get the customer's yes first. `reviewed` asks for that yes, then waits for an automated reviewer, which may hand the call to a teammate. `high` waits for a teammate's approval in the conversation.
Allowed:lowmediumreviewedhigh
visitorVisitorrequired
Who the agent is talking to. Authorize on `externalId`, and only when `verified` is true.
Show properties
verifiedbooleanrequired
True only when your server signed the visitor's identity. Always sent.
externalIdstring
Your own id for the visitor. Present only when `verified` is true.
emailstring
What the page or the customer said. Not verified.
namestring
What the page or the customer said. Not verified.
approvedBystring
Who let the call run. The approving teammate's name on approved `high` and `reviewed` calls. `The reviewer` when the automated reviewer approved it. The teammate's name when a teammate ran the tool themselves, at any risk. `A test from the CLI` for `median tools test`. `A teammate` when no name is on record. Absent when the agent called a `low` or `medium` tool.
DiagnosticsRequest
opstringrequired
Allowed:diagnostics
Responses
200The tool ran, refused, or threw. Or the diagnostics answer.
One of:
ToolResult
resultRefusal | anyrequired
Whatever the tool returned, as JSON. The agent reads the first 4,000 characters and answers from it. `medianNavigateTo` (a path on your site, up to 2,048 characters) and `medianHighlight` (a CSS selector, up to 256 characters) are removed before the agent reads it, and become a button and a highlight in the widget.
Show properties
Any of:
Refusal
okboolean
Allowed:false
knownboolean
Allowed:false
allowedboolean
Allowed:false
outcomestring
Allowed:blockedunknown
reasonstring
A short code. Defaults to `tool_refused`.
detailstring
One line the agent can use.
any
any
Error
errorobjectrequired
Show properties
codestringrequired
Allowed:execution_faileddiagnostics_unsupportedinvalid_bodyunknown_opinvalid_inputmissing_signaturemalformed_signaturestale_timestampinvalid_signatureunknown_toolmethod_not_allowedmissing_secretinvalid_median_key
messagestringrequired
Written for whoever has to fix it. On `execution_failed` this is your thrown error's message, and the agent reads it.
400The body is not a tool call, the op is unknown, or the input does not fit the tool's schema.
errorobjectrequired
Show properties
codestringrequired
Allowed:execution_faileddiagnostics_unsupportedinvalid_bodyunknown_opinvalid_inputmissing_signaturemalformed_signaturestale_timestampinvalid_signatureunknown_toolmethod_not_allowedmissing_secretinvalid_median_key
messagestringrequired
Written for whoever has to fix it. On `execution_failed` this is your thrown error's message, and the agent reads it.
401The signature is missing, malformed, stale, or from a different Median key.
errorobjectrequired
Show properties
codestringrequired
Allowed:execution_faileddiagnostics_unsupportedinvalid_bodyunknown_opinvalid_inputmissing_signaturemalformed_signaturestale_timestampinvalid_signatureunknown_toolmethod_not_allowedmissing_secretinvalid_median_key
messagestringrequired
Written for whoever has to fix it. On `execution_failed` this is your thrown error's message, and the agent reads it.
404No tool by that name, so the synced list is behind. Sync the endpoint again.
errorobjectrequired
Show properties
codestringrequired
Allowed:execution_faileddiagnostics_unsupportedinvalid_bodyunknown_opinvalid_inputmissing_signaturemalformed_signaturestale_timestampinvalid_signatureunknown_toolmethod_not_allowedmissing_secretinvalid_median_key
messagestringrequired
Written for whoever has to fix it. On `execution_failed` this is your thrown error's message, and the agent reads it.
405Only GET and POST are answered.
errorobjectrequired
Show properties
codestringrequired
Allowed:execution_faileddiagnostics_unsupportedinvalid_bodyunknown_opinvalid_inputmissing_signaturemalformed_signaturestale_timestampinvalid_signatureunknown_toolmethod_not_allowedmissing_secretinvalid_median_key
messagestringrequired
Written for whoever has to fix it. On `execution_failed` this is your thrown error's message, and the agent reads it.
500The server has no usable Median key to verify with.
errorobjectrequired
Show properties
codestringrequired
Allowed:execution_faileddiagnostics_unsupportedinvalid_bodyunknown_opinvalid_inputmissing_signaturemalformed_signaturestale_timestampinvalid_signatureunknown_toolmethod_not_allowedmissing_secretinvalid_median_key
messagestringrequired
Written for whoever has to fix it. On `execution_failed` this is your thrown error's message, and the agent reads it.
Request
curl -X POST "https://example.com/api/median/" \
  -H "median-signature: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "string",
  "toolCallId": "string",
  "input": {},
  "context": {
    "conversationId": "string",
    "risk": "low",
    "visitor": {
      "verified": true,
      "externalId": "string",
      "email": "string",
      "name": "string"
    },
    "approvedBy": "string"
  }
}'
Response
{
  "result": {
    "ok": false,
    "reason": "not_signed_in",
    "detail": "Sign in to see orders."
  }
}