A small, plain JSON API for your monitors

What the API is for

The API exists so that monitoring can be part of how you ship, not an extra place to click. Typical uses are creating monitors when a site is provisioned, pausing them during a deploy, pulling incidents into a ticketing tool or a dashboard, acknowledging an incident from a chat command, and posting a manual incident on a client's status page when you know about a problem before the checks do.

All responses are JSON, timestamps are ISO 8601 in UTC and identifiers are UUIDs. The base URL is https://app.tenium.app/api/v1, and the major version is part of the path. New fields and endpoints can appear without a version change; a breaking change would get a new major version with a long overlap, as described in API: authentication.

Authentication and access levels

Create a key under Settings, then API keys. The key is shown once, and each key is either read or write scoped. Send it as a bearer token:

curl -H "Authorization: Bearer $TENIUM_KEY" \
  https://app.tenium.app/api/v1/monitors?limit=20

Read keys work on every plan, including Free. Write keys need Pro or Agency; on a lower plan the request returns 403 with the code plan_limit, and a read-only key used for a write returns 403 with forbidden_scope. A key created by a client-workspace viewer only sees that workspace.

Examples

Create an HTTP monitor with a keyword rule, inside a client workspace:

curl -X POST https://app.tenium.app/api/v1/monitors \
  -H "Authorization: Bearer $TENIUM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client A shop",
    "type": "http",
    "url": "https://shop.clienta.com",
    "intervalSec": 60,
    "expectedStatus": "200-299",
    "keyword": { "mode": "contains", "value": "Add to cart" },
    "clientWorkspaceId": "9a8b7c6d-0000-4000-8000-000000000000",
    "tags": ["woocommerce", "client-a"]
  }'

Pause a monitor for a deploy, then resume it and ask for an immediate check:

curl -X POST -H "Authorization: Bearer $TENIUM_KEY" \
  https://app.tenium.app/api/v1/monitors/$ID/pause
# ... deploy ...
curl -X POST -H "Authorization: Bearer $TENIUM_KEY" \
  https://app.tenium.app/api/v1/monitors/$ID/resume
curl -X POST -H "Authorization: Bearer $TENIUM_KEY" \
  https://app.tenium.app/api/v1/monitors/$ID/check

List open incidents and acknowledge one:

curl -H "Authorization: Bearer $TENIUM_KEY" \
  "https://app.tenium.app/api/v1/incidents?status=open"
curl -X POST -H "Authorization: Bearer $TENIUM_KEY" \
  https://app.tenium.app/api/v1/incidents/$INCIDENT/ack

Pagination, errors and limits

• Pagination. List endpoints take limit (default 50, maximum 200) and a cursor; a response that has more results tells you where to continue.
• Errors. A JSON object with an error key containing a status, a machine-readable code such as validation, plan_limit, not_found or rate_limited, a message and, for validation problems, the field. See errors and rate limits.
• Rate limits. 600 read requests and 120 write requests per minute per key. An on-demand check is limited to one per monitor every ten seconds. Responses carry X-RateLimit-* headers, and a 429 carries Retry-After.
• Plan limits apply. Creating a monitor that exceeds your monitor count, interval floor or monitor type allowance returns 422 with plan_limit, exactly as the app would.

Heartbeats and webhooks sit outside the key

Two other integration points do not use the API key. A heartbeat monitor has its own ping URL that a cron job or CI step requests; the ID in the URL is the secret. And webhook contacts receive signed JSON events when incidents open, are acknowledged or resolve. Both are described in the docs and are worth reading together with this page if you are wiring up a pipeline: heartbeats, webhooks.

What the API does not do yet

There is no endpoint for maintenance windows, alert contacts or reports; those are managed in the app. There is no OpenAPI file or SDK. Monitors with several steps do not exist, so the API cannot define a multi-request transaction. And the assistant-friendly MCP layer on top of the API is not built; the MCP page says where that stands. Developers who want the practical walkthrough should continue to the developer page.