Median API

Version 1.0.0.

Everything the widget does, over HTTP: read a visitor's thread, send messages, attach files, and signal typing. The tool endpoint routes point the agent at the tools you serve. Server to server only. No CORS headers are sent, so a browser cannot call it directly.

The thread, message and typing endpoints take a session: a token you choose, 8 to 128 characters after trimming, naming one visitor. Use your own user id for signed in people so their conversation follows them across devices, and a random id in a cookie for everyone else. The API trusts whatever session your server sends, so never let the browser choose it.

Errors are JSON with a code and a message. Every code, the rate limits per plan and the size limits are in Errors and limits.

Base URL

https://api.median.sh/v1

Authentication

Authorization: Bearer $MEDIAN_KEY

A MEDIAN_KEY from Settings under API. It starts with median_key_ and stays on your server. The tool endpoint routes also accept an OAuth access token (median_oat_) from median login or an MCP client, acting as the person who approved it. The messaging routes accept only a Median key.

Endpoints