API overview

Base URLs

The management endpoints are also reachable over MCP and through the CLI.

Which API

Messaging

Do what the widget does, from your server. These five routes accept only a Median key.

Tool endpoint

Point the agent at the routes you serve. These accept a Median key or an OAuth token.

Management

Everything the dashboard does, one row per area. Each row links to that area in the management reference.

Tools you serve

Each route you connect answers Median's signed manifest reads and tool calls. Its contract is in the tool endpoint reference. Build it with custom tools.

Authentication

Send the credential as a bearer token.

curl https://api.median.sh/v1/config \
  -H "Authorization: Bearer $MEDIAN_KEY"

• A Median key cannot send invitations or change members. Those return needs_a_person. Use an OAuth token.
• The account routes are GET /v1/me, POST /v1/organizations and POST /v1/me/organization. A key gets 400 token_required.
• An OAuth token on a messaging route gets 401 invalid_api_key.
• A publishable key gets 401 publishable_key, except on the account routes, where it gets 400 token_required.
• A token with no organization bound gets no_organization. Run median orgs create or median orgs use.
• An access token lasts 8 hours and the client refreshes it. Token lifetimes and revocation are on the MCP page.

Error codes and statuses are in Errors and limits.

Keys

A Median key has two halves. The server half, MEDIAN_KEY, authenticates the API and signs identity, tool calls and webhooks. The public half, median_pk_, runs the widget. publicKeyFromMedianKey from @mediansh/agent-tools extracts it.

Create a key

In Settings → API, under Median keys, press Create key. From a terminal or a script:

median keys create --name production

curl https://api.median.sh/v1/keys \
  -H "Authorization: Bearer $MEDIAN_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"production"}'

The dialog shows both values once, labeled Median key · server only and Public key · safe for the browser. POST /v1/keys returns { id, key, publicKey }. Only the response holds the full key. Every later read shows it masked.

Which key signs what

The widget's public key and its identity signatures must come from the same Median key.

Adding a webhook or a tool endpoint fails with missing_median_key until a key exists.

Revoke a key

In Settings → API, press Revoke on the row, then Revoke key. The CLI is median keys revoke <id> and the API is DELETE /v1/keys/{id}. It cannot be undone. Other keys keep working.

Roles

A Median key acts as an admin. An OAuth token acts with the role its person holds now, so a role change applies to the next request. A refusal returns 403 forbidden with a sentence such as "Only admins and owners can edit the agent." The full matrix is in Roles.

CORS

/v1 sends no CORS headers. Call it from your server. /mcp, the /.well-known discovery documents and the OAuth endpoints except /oauth/authorize send Access-Control-Allow-Origin: *.

:::warning MEDIAN_KEY must never reach a browser. For a panel of your own, see Build your own widget. :::