Quickstart
Create a key under Settings → API keys in the dashboard. Choose Admin if the key should change monitoring and alerting, or Member for read-only access. The secret is shown once.
Send it as a bearer token. This lists the websites your organization monitors:
curl https://api.upcheck.so/v1/domains \
-H "Authorization: Bearer uck_your_key"Adding a website starts all four checks and probes it inline, so the response usually carries a first result:
curl -X POST https://api.upcheck.so/v1/domains \
-H "Authorization: Bearer uck_your_key" \
-H "Content-Type: application/json" \
-d '{ "domain": "www.example.com", "friendlyName": "Marketing site" }'The API reference is generated from the same schemas the API validates with, and includes a request builder and samples in several languages.
Authentication
Keys belong to an organization, not to the person who created them, so a key keeps working when a teammate leaves and every key a workspace has is visible to its admins. A key has one of two roles:
| Role | Can |
|---|---|
| admin | Read everything and change websites, alert rules, email lists, integrations, the team and the organization name. |
| member | Read everything. Every write returns 403. |
Keys cannot create other keys, and billing checkout stays in the dashboard. Revoke a key from the same settings page; revocation is immediate.
Conventions
The base URL is https://api.upcheck.so and every path starts with /v1. Bodies are JSON. Timestamps are Unix milliseconds. Identifiers are opaque strings; pass them back exactly as returned.
Updates are partial. A PATCH changes only the fields you send, so { "enabled": false } pauses an alert rule without touching its scope.
Lists that grow (check history, alert events, activity) take limit and offset. Websites, rules, lists, integrations and members are returned whole; an organization holds at most 500 websites.
Rate limit. Each key may make 300 requests per minute. A 429 carries Retry-After in seconds.
Errors
Every error is JSON with a human-readable error and a stable code:
{ "error": "A valid hostname is required.", "code": "bad_request" }| Status | Code | Meaning |
|---|---|---|
400 | bad_request | The body or parameters are invalid. error names the first problem. |
401 | unauthorized | The key is missing, invalid or revoked. |
402 | payment_required | The organization has no active subscription. |
403 | forbidden | The key is read-only, or the action needs a role the key lacks. |
404 | not_found | No such resource in this organization. |
409 | conflict | The request conflicts with current state, for example the website limit. |
429 | rate_limited | The key exceeded 300 requests in a minute. Honour Retry-After. |
Resources
| Resource | Path | What it covers |
|---|---|---|
| Domains | /v1/domains | The websites being monitored, their monitors and check history. |
| Alert rules | /v1/alert-rules | What to alert on, how often, and where. |
| Alert events | /v1/alert-events | Alerts that were delivered. |
| Email lists | /v1/email-lists | Named recipient sets for the email channel. |
| Integrations | /v1/integrations | Slack, Discord, Teams and webhook destinations. |
| Team | /v1/team/members | Members and invitations. |
| Organization | /v1/organization | The workspace the key belongs to. |
| Account | /v1/me | Key introspection, stats, activity and billing. |
Every operation, with its request and response schemas, is in the API reference. The raw document is served at https://api.upcheck.so/v1/openapi.json for client generators.
Webhook payloads
A generic webhook integration receives one JSON object per alert. The event names the check, so a receiver can route an expiring certificate to whoever owns deploys and an outage to whoever is on call:
{
"event": "uptime.alert",
"subject": "uptime",
"domain": "www.example.com",
"displayName": "Marketing site",
"status": "crit",
"daysRemaining": 0,
"title": "Site down - www.example.com",
"message": "www.example.com is not responding: HTTP 502 ...",
"url": "https://upcheck.so/dashboard/domains/…",
"timestamp": 1757900000000
}Events are ssl.alert, domain.alert, uptime.alert and dns.alert. A test sent from the dashboard or the API uses the same shape with .test appended and "test": true, so a receiver that files tickets can ignore it. Slack, Discord and Teams integrations get the payload their incoming webhooks expect instead.
AI assistants
The same operations are available as tools over the Model Context Protocol, so Claude, Cursor or any MCP client can answer “what is failing right now?” or add a website for you. See the MCP server page for setup.