Skip to content
Centoculus

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.

  1. Create a token under My account → API tokens in the web app or the phone app and pick its scopes.
  2. Copy the token right away; it is shown only once.
  3. 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.

ScopeAllows
monitors:readList and show monitors, uptime, daily uptime, response times, check types, locations, dashboard summary
monitors:writeCreate, update, delete, pause and resume monitors
servers:readList and show servers and their metrics
servers:writeCreate, update, delete, pause and resume servers; new install command for the agent
incidents:readList and show incidents, dashboard summary
status-pages:readList and show status pages
status-pages:writeCreate, update and delete status pages and their notices
notifications:readList and show notification channels and channel types
notifications:writeCreate, 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 under data with links and meta.
  • 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 page and per_page; meta carries current_page, last_page, per_page and total. 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_id when 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.

StatusMeaning
401Missing, invalid, expired or revoked token.
402Monitoring is paused because the prepaid balance is used up (reseller customers); it resumes after a top-up.
403The token lacks the scope, the endpoint is closed to API tokens, or your plan does not include the feature.
404Not found, or not in your workspace.
409Conflict, for example confirming an e-mail address that is already confirmed.
422Validation failed; see errors. When a plan limit is hit, upgrade names the feature a larger plan unlocks.
429Too 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.

EndpointWhat 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

FieldDescription
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.

EndpointWhat 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.

EndpointWhat 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]
FieldDescription
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.

EndpointWhat 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.

EndpointWhat 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)
FieldDescription
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.

EndpointWhat 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
FieldDescription
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.