API & MCP Documentation

Authentication

Every request is authenticated with an API key. Create one in Settings → API & MCP. The full key (it starts with udk_) is shown once at creation — copy it then; only a hash is stored, so it can’t be shown again. Treat a key like a password: it acts as your account.

Send it as a Bearer token in the Authorization header:

Authorization: Bearer udk_your_key_here

Scopes. Each key is either Read & write or Read-only. A read-only key can call any GET endpoint but is rejected with 403 on any create/update/delete. Revoke a key any time from Settings — it stops working immediately.

Keeping keys secure

• Store keys in a password or secrets manager. Never commit them to source control, put them in a ticket, or paste them in chat.
• Grant the least privilege that works — use a read-only key unless the tool needs to make changes.
• Give each tool or environment its own named key, so you can revoke one without disrupting the others.
• Rotate periodically: create a replacement, switch your tools over, then revoke the old key.
• If a key is ever exposed, revoke it immediately and create a new one.

Base URL & format

All REST endpoints live under the /api/v1 prefix:

https://uptimedesk.io/api/v1

Requests with a body must send Content-Type: application/json. Every response is JSON. Success responses wrap the payload in a data field; errors return an error message and a stable code:

// success
{ "data": { "id": "clx...", "name": "My site", ... } }

// error
{ "error": "This API key is read-only. Use a read-write key to make changes.",
  "code": "FORBIDDEN" }

Rate limits

Requests are limited per API key. Exceeding the limit returns 429 with a Retry-After header (seconds).

• REST API (/api/v1): 120 requests / minute per key.
• MCP server (/api/mcp): 240 requests / minute per key.

Error codes

Every failure carries an HTTP status and a machine-readable code:

Monitors

Example

curl -X POST https://uptimedesk.io/api/v1/monitors \
  -H "Authorization: Bearer udk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marketing site", "url": "https://example.com", "keyword": "Welcome" }'

Groups

Groups (called “clients” internally) organize monitors and power status pages. Creating a group requires the Pro plan.

Alert contacts

Incidents

Incidents are read-only over the API.

Account

{
  "data": {
    "plan": "PRO",
    "scope": "READ_WRITE",
    "limits": { "maxMonitors": 25, "checkIntervalMinutes": 1, "maxClients": 10,
                "statusPages": true, "slackAlerts": true },
    "usage": { "monitors": 8, "groups": 2, "alertContacts": 3 }
  }
}

MCP server (for AI agents)

The MCP server exposes the same operations as tools that any MCP-capable AI agent can call, so you can say “add a monitor for example.com and alert #ops” and the agent does it. UptimeDesk doesn’t run any AI itself here — your agent supplies the model; we just expose and execute the tools.

Endpoint (JSON-RPC 2.0 over HTTP POST, authenticated with the same API key):

https://uptimedesk.io/api/mcp

Add it to your agent’s MCP config, replacing the key with one of yours:

{
  "mcpServers": {
    "uptimedesk": {
      "url": "https://uptimedesk.io/api/mcp",
      "headers": { "Authorization": "Bearer udk_your_key_here" }
    }
  }
}

Available tools

• list_monitors, create_monitor, update_monitor, pause_monitor, delete_monitor
• list_groups, create_group, delete_group
• list_alert_contacts, create_alert_contact, delete_alert_contact
• list_incidents, get_account_usage

Write tools require a read-write key. When a tool can’t run (plan limit reached, read-only key, validation), the agent receives the reason as a tool error so it can tell you what happened.

Good to know

• Adding an alert contact makes it a live alert destination: unless a monitor sets its own contacts, new monitors auto-attach every account contact, so a Slack/email you add will start receiving real down/up alerts. Review what a connected agent creates.
• For your privacy, monitor requestHeaders values and requestBody are redacted in API and MCP responses — a connected agent never sees secrets you stored in a monitor’s custom headers. (They’re still used when the check runs.)