# API

Source: https://getuptimely.com/docs/api

> The /v1 REST API, authentication, limits, and the official TypeScript SDK.

Everything in the dashboard is programmable. The public REST API lives at
`https://app.getuptimely.com/v1` and covers monitors, incidents, alerts,
scheduled maintenance, status pages, on-call, usage, and outbound webhook
endpoints — 22 operations, documented in the
[interactive API reference](/api-reference).

## Authentication [#authentication]

Create a key under **Settings → API Keys → Public API keys** in your project
(keys are shown once and stored hashed), then send it as a Bearer token:

```bash
curl https://app.getuptimely.com/v1/monitors \
  -H "Authorization: Bearer $UPTIMELY_API_KEY"
```

Keys are project-scoped and carry the scopes you select at creation. Use **Rename** on a key to change its label; the key itself and its scopes never change.

## TypeScript SDK [#typescript-sdk]

`npm install @uptimely/sdk` — typed end to end from the same schemas the API
validates with, with built-in retries, idempotency keys and auto-pagination.
Source is mirrored at
[github.com/DevinoSolutions/uptimely-sdk](https://github.com/DevinoSolutions/uptimely-sdk).

```ts
import Uptimely from "@uptimely/sdk";

const uptimely = new Uptimely(); // reads UPTIMELY_API_KEY

for await (const monitor of uptimely.monitors.list()) {
  console.log(monitor.name, monitor.status.name);
}
```

## Errors [#errors]

Every error is an RFC 9457 `application/problem+json` document with a stable
`code` to branch on and a `type` URI that resolves to a docs page — for
example [rate\_limited](/api/problems/rate-limited) or
[validation\_failed](/api/problems/validation-failed).

## Rate limits & quotas [#rate-limits--quotas]

* **Free** — read-only API access, 1,000 requests/month, 60 requests/minute
  burst.
* **Pro** — full read + write access and webhook management, 100,000
  requests/month, 300 requests/minute burst.
* `GET /v1/usage` shows live consumption — it never consumes quota and never
  denies. Webhook deliveries don't count against your quota.

List, history and export endpoints (every `GET` that returns a collection) also
share a lower ceiling of 60 requests/minute per key on every plan, so a polling
loop cannot drain the month; single-resource reads and writes keep the rest of
the burst. Both are `429 rate_limited` — the `detail` names which one you hit.

Responses carry live `ratelimit` headers (on list endpoints the first policy is
whichever of the two windows has fewer requests left); 429s carry
`Retry-After`.

## Idempotency [#idempotency]

POST requests accept an `Idempotency-Key` header: one unique key per logical
operation, reused only for byte-identical retries. The SDK does this
automatically.

## Other machine endpoints [#other-machine-endpoints]

Not everything Uptimely exposes to machines belongs to `/v1`. These also live
on `https://app.getuptimely.com` and authenticate their own way:

* **Prometheus scrape** — `GET /api/metrics?projectId=<id>`, carrying monitor
  status and response times in the Prometheus exposition format. It
  authenticates with a **legacy project API key** (the "API Keys" card under
  Settings → API Keys, below the public keys — the same key class the MCP
  tools take), sent as `Authorization: Bearer …`. A public `uptimely_live_…`
  key is for `/v1` and is not accepted here.
* **OpenTelemetry ingestion** — `POST /api/otlp/v1/logs`, `/traces` and
  `/metrics` accept OTLP and store the data in ClickHouse. Authenticate with a
  telemetry ingestion key in the `x-uptimely-ingestion-key` header
  (`x-uptimely-service-token` and `x-uptimely-token` are accepted as aliases,
  for OTel distros that send one of those).
* **Health probe** — `GET /api/health` is public and reports the platform's
  own status, including the probe pipeline. Monitored by Uptimely itself,
  naturally.
* **Status page machine surfaces** — `GET /status/<slug>/badge` returns an
  embeddable SVG status badge and `GET /status/<slug>/rss` an incident feed.
  Both are anonymous, and both answer only for a status page marked public.

The MCP endpoint is separate again — see [MCP & AI](/mcp-and-ai).

## The machine surface, in one place [#the-machine-surface-in-one-place]

* OpenAPI 3.1 document: [/docs/api/openapi.json](/api/openapi.json)
* Interactive reference: [/docs/api-reference](/api-reference)
* Error-code pages: [/docs/api/problems/…](/api/problems/validation-failed)
