Uptime monitoring API
Everything you do in the app you can do over the REST API: create monitors from your deployment pipeline, pull uptime and response times into your own dashboards, keep status pages and alert channels in sync. JSON in, JSON out, one Bearer token. API tokens come with the Business plan and up.
Getting started
Base URL
https://app.centoculus.com/api/v1
Every request carries two headers: Authorization: Bearer <token> and Accept: application/json. Requests with a body send JSON with Content-Type: application/json.
- Create a token under My account → API tokens in the web app or the phone app and pick its scopes.
- Copy the token right away; it is shown only once.
- Call
GET /me. It works with every token and tells you whose token it is.
Your first call:
curl https://app.centoculus.com/api/v1/me \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" \
-H "Accept: application/json"
The answer is your user with role, language and the workspaces the token reaches (shortened):
{
"data": {
"id": 4821,
"name": "Mara Lindqvist",
"email": "mara@example.com",
"role": "customer_admin",
"role_label": "admin",
"locale": "en",
"timezone": "Europe/Stockholm",
"customers": [{"id": 1207, "name": "Example Ltd"}],
"default_customer_id": 1207
}
}
Tokens and scopes
A token has a name, an optional expiry (up to 730 days) and the scopes it may use. Pick only the scopes an integration needs: a dashboard gets monitors:read and incidents:read, a deployment script gets monitors:write. On plans below Business the section is visible but greyed out.
| Scope | Allows |
|---|---|
monitors:read | List and show monitors, uptime, daily uptime, response times, check types, locations, dashboard summary |
monitors:write | Create, update, delete, pause and resume monitors |
servers:read | List and show servers and their metrics |
servers:write | Create, update, delete, pause and resume servers; new install command for the agent |
incidents:read | List and show incidents, dashboard summary |
status-pages:read | List and show status pages |
status-pages:write | Create, update and delete status pages and their notices |
notifications:read | List and show notification channels and channel types |
notifications:write | Create, update and delete channels (e-mail, Telegram, webhook, push), send a test |
GET /me works with every token. Billing, team, tokens, account security and fixes are not reachable with an API token and answer 403, as does a call without the matching scope.
Revoke a token in the same place; it stops working at once.
Conventions
- Responses are JSON. A single object comes under
data, a list underdatawithlinksandmeta. - Monitors and servers are addressed by UUID; incidents, status pages and notification channels by a numeric id.
- Times are ISO 8601 in UTC, for example
2026-11-15T08:30:00.000000Z. - Lists are paginated with the query parameters
pageandper_page;metacarriescurrent_page,last_page,per_pageandtotal. Default page sizes: monitors 15 (max. 200), incidents 25 (max. 100), notification channels 50, servers 100, status pages 15. - Accounts with several workspaces (partners and resellers) pass
customer_idwhen creating something and may filter lists with it. Customer accounts leave it out. - There is no general request quota. A few endpoints are throttled, for example resending an e-mail confirmation (10 per minute); they answer 429 with
Retry-After. Poll no more often than your check interval; for live data use a webhook channel.
Errors
Errors are JSON with a message. Validation errors add errors with one list of messages per field.
| Status | Meaning |
|---|---|
401 | Missing, invalid, expired or revoked token. |
402 | Monitoring is paused because the prepaid balance is used up (reseller customers); it resumes after a top-up. |
403 | The token lacks the scope, the endpoint is closed to API tokens, or your plan does not include the feature. |
404 | Not found, or not in your workspace. |
409 | Conflict, for example confirming an e-mail address that is already confirmed. |
422 | Validation failed; see errors. When a plan limit is hit, upgrade names the feature a larger plan unlocks. |
429 | Too many requests on a throttled endpoint; wait for Retry-After seconds. |
A validation error:
HTTP/1.1 422 Unprocessable Content
{
"message": "The target field is required. (and 1 more error)",
"errors": {
"target": ["The target field is required."],
"interval_seconds": ["The interval must be at least 60 seconds on your plan."]
}
}
Monitors
A monitor is one check: a website, an SSL certificate, a ping, a TCP port, a DNS record, a cron heartbeat or the mail setup of a domain. Types: http, ssl, ping, tcp, dns, heartbeat, maildns, mailflow. GET /check-types tells you which types, intervals and locations your plan includes and the defaults of every type.
| Endpoint | What it does |
|---|---|
GET /monitors |
List; filters status, search, ids (comma-separated), with_stats=1 adds uptime and last response time |
POST /monitors |
Create; checks start in the background |
GET /monitors/{id} |
One monitor with its locations and open incident |
PATCH /monitors/{id} |
Update; the type cannot change |
DELETE /monitors/{id} |
Delete (204) |
POST /monitors/{id}/pause |
Pause; an open incident is closed |
POST /monitors/{id}/resume |
Resume |
GET /check-types |
Types, defaults and the limits of your plan |
GET /locations |
Active check locations (code, name, country) |
Fields when creating
| Field | Description |
|---|---|
name |
Display name, up to 255 characters. Required. |
type |
One of the types above. Required, fixed afterwards. |
target |
URL, host name, IP address or domain, depending on the type. Required except for heartbeat, which gives you a ping URL instead. |
interval_seconds |
Check interval. The minimum depends on your plan; GET /check-types returns it as limits.min_interval_seconds. |
locations |
Location codes, for example ["eu", "sg"]. How many you may choose depends on your plan. |
primary_location |
Main location that confirms outages first (Smart Verify). |
confirm_locations |
How many locations must see the failure before you are alerted (1–3). Configurable on larger plans. |
confirm_checks |
How many failed checks in a row confirm an outage (1–3). Configurable on larger plans. |
options |
Per type. For http: method (GET, HEAD, POST), expected_status (e.g. 200-399 or 200,301), keyword with keyword_mode (present or absent), timeout_seconds, check_ssl, warn_days, crit_days, allow_self_signed. Omitted options take the defaults from GET /check-types. |
Create a website check with a keyword:
curl -X POST https://app.centoculus.com/api/v1/monitors \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"name": "Shop",
"type": "http",
"target": "https://shop.example.com",
"interval_seconds": 60,
"locations": ["eu", "sg"],
"options": {"keyword": "Add to cart", "expected_status": "200-399"}
}'
The response (201) is the monitor. provisioning.state turns to synced as soon as the locations have taken it over, status from pending to up after the first check:
{
"data": {
"id": "6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44",
"customer_id": 1207,
"name": "Shop",
"type": "http",
"target": "https://shop.example.com",
"interval_seconds": 60,
"options": {
"method": "GET",
"expected_status": "200-399",
"keyword": "Add to cart",
"keyword_mode": "present",
"timeout_seconds": 10,
"check_ssl": true,
"warn_days": 14,
"crit_days": 3,
"allow_self_signed": false
},
"location_codes": ["eu", "sg"],
"primary_location": "eu",
"smart_verify": true,
"confirm_locations": 1,
"confirm_checks": 1,
"status": "pending",
"is_paused": false,
"provisioning": {"state": "pending"},
"locations": [
{"code": "eu", "role": "primary", "name": "Europe", "status": "pending", "last_response_ms": null, "last_checked_at": null},
{"code": "sg", "role": "verify", "name": "Singapore", "status": "pending", "last_response_ms": null, "last_checked_at": null}
],
"open_incident": null,
"last_checked_at": null,
"status_changed_at": null,
"created_at": "2026-11-15T08:30:12.000000Z",
"updated_at": "2026-11-15T08:30:12.000000Z"
}
}
Status values: pending, up, degraded, down, paused.
Pause a monitor during a deployment and resume it afterwards:
curl -X POST https://app.centoculus.com/api/v1/monitors/6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44/pause \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" -H "Accept: application/json"
curl -X POST https://app.centoculus.com/api/v1/monitors/6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44/resume \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" -H "Accept: application/json"
Uptime and response times
Uptime is computed from outages (incidents of severity major); warnings such as an expiring certificate do not count. Not checked yet means null, not 100.
| Endpoint | What it does |
|---|---|
GET /monitors/{id}/uptime |
Uptime in percent for the last 24 hours, 7 days and 30 days |
GET /monitors/{id}/daily-uptime |
Uptime per calendar day (UTC), days 1–90, default 30 |
GET /monitors/{id}/response-times |
Response time and availability per location, range 24h, 7d or 30d; hourly points, daily for 30d |
Uptime:
curl https://app.centoculus.com/api/v1/monitors/6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44/uptime \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" -H "Accept: application/json"
{"data": {"24h": 100, "7d": 99.952, "30d": 99.987}}
Response times (shortened):
curl "https://app.centoculus.com/api/v1/monitors/6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44/response-times?range=24h" \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" -H "Accept: application/json"
{
"data": {
"range": "24h",
"locations": {
"eu": [
{"time": "2026-11-15T07:00:00+00:00", "avg_ms": 212.4, "min_ms": 180, "max_ms": 402, "availability": 100},
{"time": "2026-11-15T08:00:00+00:00", "avg_ms": 230.1, "min_ms": 190, "max_ms": 388, "availability": 100}
],
"sg": [
{"time": "2026-11-15T07:00:00+00:00", "avg_ms": 512.8, "min_ms": 470, "max_ms": 790, "availability": 100}
]
}
}
}
Servers
A server is a machine with the agent on it, which reports CPU, memory, load, disks, network and services. Creating a server returns the one-time install command; run it on the machine and the server appears a moment later.
| Endpoint | What it does |
|---|---|
GET /servers |
List; filter ids |
POST /servers |
Create; the response carries install_command (Linux) and install_command_freebsd |
GET /servers/{id} |
One server with inventory, latest snapshot and thresholds |
PATCH /servers/{id} |
Rename, choose the watched services, set thresholds |
DELETE /servers/{id} |
Delete (204); the agent is removed from monitoring |
POST /servers/{id}/pause |
Pause; open incidents are closed |
POST /servers/{id}/resume |
Resume |
POST /servers/{id}/install-token |
New install command; rotate_key=true also issues a new agent key |
GET /servers/{id}/metrics |
Chart series, range 24h, 7d or 30d: metric → context → [unix time, avg, min, max] |
| Field | Description |
|---|---|
name |
Display name, up to 100 characters. Required when creating. |
services |
Service names the agent should watch, for example ["nginx", "php8.4-fpm", "mariadb"]; up to 200. The server reports what it found under discovered.services. |
thresholds |
Alert thresholds: cpu_max (percent), load_max_per_cpu, mem_min_pavail (percent free), fs_warn and fs_crit (percent used), inode_warn, agent_nodata_minutes, per mount point under filesystems, and the regular expressions fs_types, fs_exclude, net_exclude. Omitted values keep the defaults. |
Add a server and read the install command from the answer:
curl -X POST https://app.centoculus.com/api/v1/servers \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"name": "web-1"}'
{
"data": {
"id": "a3b9d6e2-5f10-4b8c-9e77-2c4d1a0f6b58",
"customer_id": 1207,
"name": "web-1",
"status": "pending",
"is_paused": false,
"provisioning": {"state": "pending"},
"services": [],
"install_token_expires_at": "2026-11-16T08:30:12.000000Z",
"install_command": "curl -fsSL https://app.centoculus.com/install/K7xQ2mVt9…Rd | sudo sh",
"install_command_freebsd": "fetch -qo - https://app.centoculus.com/install/K7xQ2mVt9…Rd | sh",
"created_at": "2026-11-15T08:30:12.000000Z"
}
}
Watch three services and alert at 80 percent disk use:
curl -X PATCH https://app.centoculus.com/api/v1/servers/a3b9d6e2-5f10-4b8c-9e77-2c4d1a0f6b58 \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"services": ["nginx", "php8.4-fpm", "mariadb"],
"thresholds": {"fs_warn": 80, "fs_crit": 90}
}'
Incidents
An incident is one outage or warning of a monitor or server, from started_at until resolved_at. Every incident carries its alert number, the same one the alert e-mail shows.
| Endpoint | What it does |
|---|---|
GET /incidents |
Newest first; filters monitor_id, status (open or closed), open=1 (open outages without notices), from and to (dates) |
GET /incidents/{id} |
One incident with its timeline: when which location went down and recovered, and the fix that handled it |
Open incidents:
curl "https://app.centoculus.com/api/v1/incidents?status=open&per_page=10" \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" -H "Accept: application/json"
{
"data": [
{
"id": 90412,
"monitor_id": "6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44",
"monitor_name": "Shop",
"server_id": null,
"subject_type": "monitor",
"severity": "major",
"cause": "unreachable",
"started_at": "2026-11-15T09:14:03.000000Z",
"resolved_at": null,
"duration_seconds": 241,
"alert_number": 101,
"alert_label": "Incident #101",
"affected_locations": ["eu", "sg"],
"failure_reason": "HTTP 502 instead of 200-399",
"fix": null
}
],
"links": {"first": "…?page=1", "last": "…?page=1", "prev": null, "next": null},
"meta": {"current_page": 1, "from": 1, "last_page": 1, "per_page": 10, "to": 1, "total": 1}
}
Useful fields: subject_type (monitor or server), severity (major, warning, info), cause (for example unreachable, network_issue, certificate_expiring, heartbeat_missed), duration_seconds, affected_locations and, while open, failure_reason with the latest check values.
Status pages
A status page shows chosen monitors to the public or to your team, under our domain or your own. Notices announce maintenance or explain an ongoing incident.
| Endpoint | What it does |
|---|---|
GET /status-pages |
List |
POST /status-pages |
Create |
GET /status-pages/{id} |
One page with monitors, notices and the state of its domains |
PATCH /status-pages/{id} |
Update; monitors replaces the whole list |
DELETE /status-pages/{id} |
Delete (204) |
POST /status-pages/{id}/notices |
Add a notice |
PUT /status-pages/{id}/notices/{notice} |
Update a notice |
DELETE /status-pages/{id}/notices/{notice} |
Remove a notice (204) |
| Field | Description |
|---|---|
slug |
Address part, 3–63 characters, lowercase letters, digits and hyphens; unique. Required. |
title |
Heading of the page. Required. |
description |
Short text under the heading, up to 2000 characters. |
logo_url |
HTTPS address of a logo. |
custom_domain |
Own domain such as status.example.com; needs a plan with own status domains. |
is_public |
Public (true) or only for signed-in users. |
monitors |
Ordered list of {"id": "<monitor UUID>", "display_name": "…", "group": "…"}; display_name and group are optional. |
A notice has kind (maintenance, info or incident), title, body (optional, up to 5000 characters), starts_at and an optional ends_at.
Create a public status page with two monitors:
curl -X POST https://app.centoculus.com/api/v1/status-pages \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"slug": "example-status",
"title": "Example status",
"is_public": true,
"monitors": [
{"id": "6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44", "display_name": "Online shop", "group": "Web"},
{"id": "9c2d4e6f-1a3b-4c5d-8e7f-6a5b4c3d2e1f", "group": "Web"}
]
}'
Announce a maintenance window:
curl -X POST https://app.centoculus.com/api/v1/status-pages/318/notices \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"kind": "maintenance",
"title": "Database upgrade",
"body": "Checkout will be unavailable for about 15 minutes.",
"starts_at": "2026-11-20T01:00:00Z",
"ends_at": "2026-11-20T01:30:00Z"
}'
Notification channels
A notification channel is one way to reach someone: an e-mail address, a Telegram chat, a webhook or the push devices of a user. A channel receives the alerts of all monitors of the workspace, or only of the monitors in monitor_ids. Which channel types your plan includes: GET /notification-channel-types.
| Endpoint | What it does |
|---|---|
GET /notification-channels |
List |
POST /notification-channels |
Create; for a webhook the signing secret is in this response only |
GET /notification-channels/{id} |
One channel |
PATCH /notification-channels/{id} |
Update; the type cannot change |
DELETE /notification-channels/{id} |
Delete (204) |
POST /notification-channels/{id}/test |
Send a test notification (202); an unconfirmed e-mail address gets its confirmation link again instead |
GET /notification-channel-types |
Channel types with available and paid |
| Field | Description |
|---|---|
type |
email, telegram, webhook or push. Required, fixed afterwards. |
name |
Display name. Required. |
config |
Per type: {"email": "…"}, {"chat_id": "…"} or {"url": "https://…"}. Push needs no config. A new e-mail address must be confirmed by link before alerts go out. |
monitor_ids |
UUIDs of the monitors this channel is for; leave it out for all monitors. |
quiet_hours |
{"start": "22:00", "end": "07:00", "timezone": "Europe/Berlin"}: no alerts in that window. |
escalation_delay_minutes |
Alert this channel only when an outage lasts this long (0–1440). |
notify_recovery |
Also send the all-clear (true or false). |
is_active |
Switch the channel on or off without deleting it. |
Create a webhook channel for two monitors and keep the secret:
curl -X POST https://app.centoculus.com/api/v1/notification-channels \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"type": "webhook",
"name": "Ops bot",
"config": {"url": "https://hooks.example.com/centoculus"},
"monitor_ids": ["6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44", "9c2d4e6f-1a3b-4c5d-8e7f-6a5b4c3d2e1f"],
"notify_recovery": true
}'
{
"data": {
"id": 512,
"customer_id": 1207,
"type": "webhook",
"name": "Ops bot",
"config": {"url": "https://hooks.example.com/centoculus", "secret": "wq7Hc2…48 characters…Zp"},
"quiet_hours": null,
"escalation_delay_minutes": 0,
"notify_recovery": true,
"is_active": true,
"confirmed": true,
"monitor_ids": ["6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44", "9c2d4e6f-1a3b-4c5d-8e7f-6a5b4c3d2e1f"],
"created_at": "2026-11-15T08:41:55.000000Z",
"updated_at": "2026-11-15T08:41:55.000000Z"
}
}
Webhook payload
A webhook channel POSTs every alert as JSON to your URL, with a 10-second timeout and no redirects. The target must be a public address.
Headers: X-Webhook-Timestamp (Unix time), X-Webhook-Signature (sha256= followed by the HMAC-SHA256 of <timestamp>.<body> with the channel secret as key) and User-Agent: Uptime-Webhook/1.
event is down, recovered, paused or test. For a monitor alert the body carries monitor (id, name, target) and incident (id, severity, cause, started_at, resolved_at, duration_seconds, affected_locations); for a server alert server (id, name) and incident with problem instead of the locations. subject is the headline of the alert in the language of the channel.
Body of a down alert:
POST /your-endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Uptime-Webhook/1
X-Webhook-Timestamp: 1794912843
X-Webhook-Signature: sha256=3f1b9c…e2a7
{
"event": "down",
"monitor": {"id": "6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44", "name": "Shop", "target": "https://shop.example.com"},
"incident": {
"id": 90412,
"severity": "major",
"cause": "unreachable",
"started_at": "2026-11-15T09:14:03+00:00",
"resolved_at": null,
"duration_seconds": 0,
"affected_locations": ["eu", "sg"]
},
"subject": "DOWN: Shop"
}
Verify the signature before you trust the body: compute the HMAC over the raw body exactly as received and compare it in constant time. Reject timestamps older than a few minutes.
Checking the signature in a shell:
expected="sha256=$(printf '%s.%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')"
[ "$expected" = "$SIGNATURE" ] && echo "valid"
Dashboard summary
GET /dashboard returns the counts behind the tiles of the overview: monitors per status (servers count with their plan units), servers per status and the number of open incidents. Any of monitors:read, servers:read or incidents:read opens it.
curl https://app.centoculus.com/api/v1/dashboard \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" -H "Accept: application/json"
{
"data": {
"monitors": {"pending": 0, "up": 46, "degraded": 1, "down": 1, "paused": 2},
"monitors_total": 50,
"servers": {"pending": 0, "up": 3, "degraded": 0, "down": 0, "paused": 0},
"open_incidents": 2
}
}
Frequently asked questions
Which plan includes the API?
API tokens come with the Business plan and up. On smaller plans you see the section under My account, greyed out with an upgrade link. Everything else in Centoculus works without the API.
Can one token do everything my account can do?
No. A token only reaches the areas you gave it scopes for, and never billing, team members, other tokens, account security or fixes. Those stay in the app.
Is there a sandbox?
Use a token with read scopes only to explore, and create test monitors on the free plan of a second account. Monitors you create count towards your plan like those made in the app.
How do I get alerts into my own system?
Create a webhook channel and verify the signature of each delivery. Every outage, recovery and pause reaches your URL within seconds, with the monitor, the cause and the affected locations as JSON.
Does the API change?
The version is in the address (/api/v1). New fields may be added to responses at any time; fields are not removed or renamed within a version. Read what you need and ignore the rest.
Ready to automate your monitoring?
API tokens are included in the Business plan and up. Compare the plans, or start free and upgrade when your scripts are ready.