> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmcpulse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/mcp/overview) 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
```

> [!NOTE]
>
> 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`](https://api.getmcpulse.com/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](/api/concepts/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](/api/concepts/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](/api/concepts/authentication)**
>
> Two credentials, and which one goes where.

> **[Ingest](/api/concepts/ingest)**
>
> Batches, the 202, and why invalid items are dropped silently.

> **[Date ranges](/api/concepts/date-ranges)**
>
> from, to, defaults, and why every day is a UTC day.

> **[The nightly pass](/api/concepts/nightly-pass)**
>
> Why three metrics lag by a day, and what nightly\_as\_of means.

> **[Errors](/api/concepts/errors)**
>
> The error shape and what each status means.

> **[Rate limits](/api/concepts/rate-limits)**
>
> Payloads per minute, and Retry-After.

> **[Versioning](/api/concepts/versioning)**
>
> The wire version, and what counts as breaking.

> **[Security](/security)**
>
> Isolation, key handling, and what is never recorded.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.