POST /
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.
Part of Tools you serve.
Request body
application/json, required.
Responses
| Status | Description |
|---|---|
200 | The tool ran, refused, or threw. Or the diagnostics answer. |
400 | The body is not a tool call, the op is unknown, or the input does not fit the tool's schema. |
401 | The signature is missing, malformed, stale, or from a different Median key. |
404 | No tool by that name, so the synced list is behind. Sync the endpoint again. |
405 | Only GET and POST are answered. |
500 | The server has no usable Median key to verify with. |
Example response
{
"result": {
"found": true,
"status": "shipped"
}
}Example request
curl -X POST https://example.com/api/median/ \
-H "median-signature: $MEDIAN_SIGNATURE" \
-H "content-type: application/json" \
-d '{"tool":"refundOrder","toolCallId":"k979r4g3v1q8x2m5n7p0s6t9w1y3z5a2","input":{"orderNumber":"ORD-1042","reason":"damaged"},"context":{"conversationId":"js7d2kq9m4x8v1n6b3c5f0h2j7l4p9r","risk":"high","visitor":{"verified":true,"externalId":"user_42","email":"ada@example.com","name":"Ada"},"approvedBy":"Nadia"}}'