Tool endpoint

Version 1.0.0.

The signed requests Median sends to your server. This is the one API in these docs you implement rather than call. median() from @mediansh/agent-tools answers all of them, so most people never write these by hand.

• Manifest. A signed GET. Answer with every tool you serve.
• Tool call. A signed POST with tool, toolCallId, input and context. Answer 200 with { result }.
• Diagnostics. A signed POST with { "op": "diagnostics" }, sent when a report is filed on Signal.

Signatures:

• Every request carries median-signature: t=<ms>,v1=<hex>. The same value is also sent as portal-signature.
• v1 is the HMAC SHA-256 of ${t}.${body}, where body is the raw request body, or the empty string for GET.
• The HMAC key is the tool signing secret derived from MEDIAN_KEY with medianSecret(MEDIAN_KEY, "tools").
• Compare in constant time. Refuse timestamps more than five minutes from your clock.

Delivery:

• Median waits 10 seconds for an answer, never follows redirects, and reads at most 100 KB of a response.
• Every error wears { "error": { "code", "message" } }.
• Set Cache-Control: private, no-store on every response.

Connecting a route is a separate request you send to your own route. It is a GET with Authorization: Bearer $MEDIAN_KEY and no signature. median() answers it by registering the route with Median. It never returns the manifest, and without the right key it answers 401 unauthorized.

Base URL

https://example.com/api/median

Authentication

median-signature: $MEDIAN_SIGNATURE

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.

Endpoints