Overview

The MCPulse REST API. Ingest telemetry, read every metric the dashboard shows, and manage MCPs, keys and the account.

The API is the product. The dashboard is one client; the MCP server is another. Every number is computed server-side so that both get the same answer, and nothing important lives in the frontend.

That is not an aspiration — the route handlers verify the token, confirm access, call a service and return. Any arithmetic in a handler would be arithmetic another client has to reimplement, so none appears.

Base URL

https://api.getmcpulse.com

This is also the SDK’s default endpoint, so a wrapped server needs no endpoint option. The Railway host it used to name still answers, but it is an implementation detail and nothing should be pointed at it.

The interactive reference is served by the API itself at /docs, generated from the same Zod route definitions that validate the requests — so it cannot drift from the code.

Two kinds of auth

Surface	Credential
POST /v1/ingest	An ingest key, mp_live_…, as a Bearer token
Everything else	A Supabase access token, as a Bearer token

They are isolated by design: an ingest key cannot read a metric, and a session token cannot post telemetry. See Authentication.

Request format

• JSON bodies with Content-Type: application/json
• All responses are JSON
• Fields are snake_case
• Timestamps are ISO 8601, UTC
• Dates are YYYY-MM-DD, and always whole UTC days

Status codes

Code	Meaning
200	Success
202	Accepted — ingest only, body intentionally empty
400	Bad request — malformed body or parameters
401	Missing, malformed, invalid or revoked credential
403	Valid credential, but your role does not permit this
404	Not found — or not yours
413	Ingest batch larger than 500 items
429	Rate limit exceeded
500	Server error

See Errors.

The endpoints

Ingest — POST /v1/ingest

MCPs — GET/POST /v1/mcps, GET/PATCH/DELETE /v1/mcps/{id}

Metrics — /v1/mcps/{id}/overview, /tools, /tools/{name}, /insights, /sessions

Keys — GET/POST /v1/mcps/{id}/keys, DELETE /v1/keys/{keyId}

Account — /v1/account, /usage, /members, /profile, /company, /notifications

Health — GET /health

Concepts

Authentication

Two credentials, and which one goes where.

Ingest

Batches, the 202, and why invalid items are dropped silently.

Date ranges

from, to, defaults, and why every day is a UTC day.

The nightly pass

Why three metrics lag by a day, and what nightly_as_of means.

Errors

The error shape and what each status means.

Rate limits

Payloads per minute, and Retry-After.

Versioning

The wire version, and what counts as breaking.

Security

Isolation, key handling, and what is never recorded.