# Uptimeify Documentation, Full Export
> Expanded, text-first export of the Uptimeify documentation with page content.
Compact index: https://docs.uptimeify.io/llms.txt
## MCP Server
Uptimeify runs a stateless Model Context Protocol server. 20 check tools work with no account and no token; 23 more read your own monitors, alerting, status pages, Incident Management (incidents, on-call, teams, schedules) and account data with an API token.
- Endpoint: `POST https://uptimeify.io/mcp` (Streamable HTTP, stateless)
- Server card: https://uptimeify.io/.well-known/mcp/server-card.json
- Registry manifest: https://uptimeify.io/.well-known/mcp/server.json
- Overview: https://uptimeify.io/mcp-server
- Technical reference: https://docs.uptimeify.io/api/mcp
- Limits: 120 requests/minute per IP on the endpoint, plus 15-30/minute per anonymous tool and 60/minute per authenticated tool. Exceeding a limit returns HTTP 429.
- Anonymous tools: check_ssl, check_dns, dns_propagation, mx_lookup, spf_check, dkim_check, dmarc_check, dnsbl_check, whois, domain_expiry, http_headers, hsts_check, redirect_check, port_check, ping_test, website_status, response_time, ip_geolocation, asn_lookup, reverse_dns
- API-token tools (read-only): list_monitors, monitor_status, list_incidents, check_history, uptime_summary, list_alert_channels, alert_history, list_status_pages, list_status_page_components, list_status_page_maintenances, get_status_page_maintenance, list_maintenance_windows, list_im_incidents, get_im_incident, who_is_on_call, list_im_teams, get_im_team, list_im_schedules, get_im_schedule, get_organization, list_users, list_customers, billing_summary
- 65 write tools over an OAuth connection with the matching write scope, switched on or off per deployment, never available to an API token: pause_monitor, resume_monitor, rename_monitor, set_check_interval, create_website_monitor, delete_monitor, acknowledge_incident, resolve_incident, post_incident_update, delete_incident, create_incident, update_incident, publish_postmortem, backfill_incident, create_maintenance_window, update_maintenance_window, delete_maintenance_window, create_status_page, update_status_page, update_status_page_design, delete_status_page, add_status_page_domain, verify_status_page_domain, activate_status_page_domain, delete_status_page_domain, create_status_page_component, update_status_page_component, delete_status_page_component, create_status_page_component_group, update_status_page_component_group, delete_status_page_component_group, create_status_page_maintenance, update_status_page_maintenance, complete_status_page_maintenance, cancel_status_page_maintenance, post_status_page_maintenance_update, create_notification_channel, update_notification_channel, delete_notification_channel, create_tag, update_tag, delete_tag, add_monitor_tag, remove_monitor_tag, create_custom_field, update_custom_field, delete_custom_field, create_report, update_report, delete_report, update_user, create_customer, update_customer, delete_customer, add_customer_domain, delete_customer_domain, add_customer_ip, delete_customer_ip, acknowledge_im_incident, resolve_im_incident, set_im_incident_status, comment_on_im_incident, assign_im_incident, set_im_incident_severity, snooze_im_incident
## Free Status Pages
Uptimeify status pages are permanently free. They need no paid plan, no trial and no monitoring, and they stay online and free if a monitoring plan ends. They are hosted in the EU.
- White-label: custom domain with automatic HTTPS, nine layouts, your own logo and colors, no Uptimeify branding, the optional "Powered by" line shows your own product name
- Incidents and maintenance: updates in phases, templates, scheduled maintenance, public postmortems
- Subscribers: email, Slack, Microsoft Teams, webhook, RSS and Atom
- Private pages: login, SSO, password, IP allowlist and audience groups
- Embeds: status badge and iframe widget
- Components: from your own monitors, third-party providers, by hand or via API
- Overview: https://uptimeify.io/status-pages
- Pricing: https://uptimeify.io/pricing
- Documentation: https://docs.uptimeify.io/status-pages
## Overview
### Welcome to Uptimeify
URL: https://docs.uptimeify.io
Description: White-label uptime, SSL & synthetic monitoring for agencies, hosted in the EU.
Summary: Uptimeify is a **white-label monitoring platform for agencies and MSPs**. Watch your clients' websites and infrastructure, alert the right people the moment something breaks, and give every client a branded status page and automated report, all under your own brand, hosted in the EU. ## What you can monitor From a single dashboard you can run: - **Websites**: uptime, SSL certificate, response time, keyword presence, page size, and HTTPS-redirect checks. - **Servers & services**: DNS, ICMP (ping), SSH, FTP, SMTP, IMAP/POP, TCP Port, DNSBL blacklist and domain-expiry checks. - **Synthetic & scheduled**: multi-step browser flows with Playwright, and Heartbeat (cron) checks for background jobs. See [Monitoring](/monitoring) for every check type and how to tune intervals, thresholds and locations. ## Alerting that doesn't cry wolf A failed check is confirmed from **another EU location** before an incident opens, so you alert on real outages, not network blips. How many locations must confirm is set per package (1 = alert immediately). Route alerts to **29 notification channels** (Slack, Microsoft Teams, PagerDuty, Opsgenie, SMS, email, webhooks and more) with multi-step, time-based escalation so an unacknowledged alert moves to the next responder. Learn how detection works in [Incidents](/incidents), and wire up channels in [Integrations](/integrations). ## Client-facing, under your brand - **Status pages**: branded, public or password-protected, on your own custom domain. See [Status Pages](/status-pages). - **Automated PDF reports**: with your logo, to justify recurring fees. - **Maintenance windows**: suppress alerts during planned work. See [Maintenance](/maintenance). ## Built for agencies Unlimited sub-accounts per client, margin control on care plans, and a full **REST API** to automate customers, monitors, status pages and notification channels. Start with the [API Documentation](/api), or manage it all as code with [Terraform & OpenTofu](/terraform). ## Pick a topic Set up website, uptime, SSL, and synthetic monitors and tune their checks. Publish branded, public or password-protected status pages for your clients. Understand how incidents are detected, confirmed, and resolved. Schedule maintenance windows to suppress alerts during planned work. Connect Slack, webhooks, and other notification channels. Automate everything with the REST API: customers, monitors, status pages. Manage monitors, status pages and incident management as code.
## API Reference
### API Documentation
URL: https://docs.uptimeify.io/api
Description: Overview of the REST API. Select a resource from the left.
Summary: ## AI / LLM Text Exports - [LLMS index for AI agents](https://uptimeify.io/llms) - [LLMS full reference for AI ingestion](https://uptimeify.io/llms-full) - [German LLMS index for AI agents](https://uptimeify.io/de/llms) - [German LLMS full reference for AI ingestion](https://uptimeify.io/de/llms-full) ## Base URL All examples use a placeholder base URL: ```bash BASE_URL="https://uptimeify.io" ``` ## Authentication Most endpoints require authentication. ```bash TOKEN="wsm_" curl -H "Authorization: Bearer $TOKEN" "$BASE_URL/api/websites" ``` API tokens generated in the dashboard always start with `wsm_`. Make sure you include the full token (including the prefix), otherwise the API will return `401 Unauthorized`. ## UUID Path Parameters For migrated resources, path parameters use the resource `publicId` UUID in the docs and examples. - Use UUIDs for endpoint paths such as `/api/websites/:websitePublicId`, `/api/customers/:customerPublicId`, `/api/organizations/:organizationPublicId`, `/api/incidents/:incidentPublicId`, `/api/customer-ips/:customerIpPublicId`, `/api/customer-domains/:customerDomainPublicId`, and monitor-specific `:...PublicId` parameters. - Internal numeric `id` fields may still appear in response payloads for internal references. - Query/body fields like `customerId`, `websiteId`, or `organizationId` stay numeric unless the endpoint page explicitly says otherwise. ## Responses and Errors - `2xx` indicates success - `4xx` indicates a request/auth problem - `5xx` indicates a server error - [Error codes and known API pitfalls](/api/error-codes-and-known-pitfalls) Example error response: ```json { "statusCode": 401, "statusMessage": "Unauthorized" } ```
### Global Administration
URL: https://docs.uptimeify.io/api/admin
Description: This section covers the global administration endpoints, which are protected and only accessible to platform administrators.
Summary: *(Endpoints are still being documented)* ## Endpoints
### Agent authentication (agentic registration)
URL: https://docs.uptimeify.io/api/agent-auth
Description: Register an AI agent and receive a short-lived, read-only access token for the Uptimeify API.
Summary: Uptimeify runs a WorkOS-style **agentic-registration authorization server** at `https://uptimeify.io`. Agents register, exchange a service-signed identity assertion for a short-lived opaque access token, and call the **read-only** API. All endpoints below are served only on the canonical host `uptimeify.io` (a 404 is returned on custom domains). ## Discover ```bash curl https://uptimeify.io/.well-known/oauth-authorization-server curl https://uptimeify.io/.well-known/oauth-protected-resource ``` The authorization-server metadata follows [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414) (`token_endpoint`, `revocation_endpoint`, `jwks_uri`, `grant_types_supported`, `scopes_supported`) and adds an `agent_auth` extension block with `identity_endpoint`, `claim_endpoint`, `identity_types_supported` (`["anonymous", "service_auth"]`, plus `"identity_assertion"` when Uptimeify trusts an identity provider), and a `skill` pointer to `/auth.md`. Only in that last case does the block also carry `identity_assertion`, `events_supported` and `events_endpoint`; see [Identity assertion (ID-JAG)](/api/agent-auth/identity-assertion). The protected-resource metadata follows [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728). ## Register (anonymous) ```bash curl -X POST https://uptimeify.io/agent/identity \ -H 'Content-Type: application/json' \ -d '{"type":"anonymous"}' ``` ```json { "registration_id": "reg_…", "identity_assertion": "", "pre_claim_scopes": ["tools.public"], "post_claim_scopes": ["api.read"], "token_endpoint": "https://uptimeify.io/oauth2/token" } ``` The `identity_assertion` is a ~24h EdDSA JWT: your durable credential. Rate limit: 30 requests/minute per caller. `post_claim_scopes` describes the scope a claimed registration reaches (`api.read`). An anonymous registration is active immediately with `tools.public` and is **usable as-is**: claiming it is optional. The response also carries a single-use `claim_token` (`clm_…`) and a `claim_url`: if you want to upgrade this registration to `api.read`, see [Claim flow](/api/agent-auth/claim-flow) for how to redeem it. ## Register (service_auth) `service_auth` registration is claimable-only: it starts `pending` and mints no token until a signed-in user authorizes it. See [Claim flow](/api/agent-auth/claim-flow) for the full `POST /agent/identity {"type":"service_auth", "login_hint":"…"}` request, the human consent step, and how to poll `/oauth2/token` for the resulting `api.read` access token. ## Register (identity_assertion) An agent signed in at a trusted identity provider registers with an ID-JAG. When its verified email belongs to an Uptimeify account, the account holder approves it on `/claim` and chooses which write areas it may use (none are preselected); the resulting token never exceeds that user's current role. See [Identity assertion (ID-JAG)](/api/agent-auth/identity-assertion). ## Exchange for an access token ```bash curl -X POST https://uptimeify.io/oauth2/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \ --data-urlencode 'assertion=' ``` ```json { "access_token": "wsma_…", "token_type": "Bearer", "expires_in": 3600, "scope": "tools.public" } ``` The access token is opaque, expires after 1 hour (3600s), and must be re-minted from the identity assertion afterward. Rate limit: 60 requests/minute per caller. ## Use (read-only) ```bash curl https://uptimeify.io/api/tools/dns-lookup?domain=deinkunde.com \ -H 'Authorization: Bearer wsma_…' ``` Agent tokens are read-only, with one exception: a token for an ID-JAG agent carries the write areas its user approved (see [Identity assertion (ID-JAG)](/api/agent-auth/identity-assertion)). The anonymous `tools.public` scope reaches only the public check tools (`GET /api/tools/*`). A claimed, `api.read`-scoped token (see [Claim flow](/api/agent-auth/claim-flow)) additionally reaches `GET /api/websites*`, `GET /api/incidents*`, a…
### Claim flow (service_auth & anonymous)
URL: https://docs.uptimeify.io/api/agent-auth/claim-flow
Description: How an agent turns a registration into a read-only, account-scoped access token by having a signed-in user authorize it.
Summary: # Claim flow A **claim** binds an agent's registration to a signed-in user's organization (or a single customer within it), granting a **read-only** (`api.read`) access token. `anonymous` and `service_auth` agents never gain write access this way; only an ID-JAG agent can be approved for write areas (see [Identity assertion (ID-JAG)](/api/agent-auth/identity-assertion), which reuses steps 3 and 4 below). There are two ways to reach a claim on this page: - **`service_auth`** registration starts a claim ceremony immediately and returns the `user_code` directly to the calling agent (a trusted, device-flow-style integration). - An **`anonymous`** registration (see [Agent authentication](/api/agent-auth)) is usable immediately and can *optionally* be upgraded later via `POST /agent/identity/claim`: the `user_code` is never returned to the agent on this path; only the signed-in user sees it. ## 1. Register with `service_auth` `POST https://uptimeify.io/agent/identity` | Field | Type | Required | Description | | --- | --- | --- | --- | | `type` | string | yes | `"service_auth"` | | `login_hint` | string | yes | Email of the user who will authorize the agent. Must contain `@`. | ```bash curl -X POST https://uptimeify.io/agent/identity \ -H 'Content-Type: application/json' \ -d '{"type":"service_auth","login_hint":"user@deinkunde.com"}' ``` ```json { "registration_id": "reg_…", "claim": { "user_code": "WDJB-MJHT", "verification_uri": "https://uptimeify.io/claim", "expires_in": 600, "interval": 5 }, "claim_token": "clm_…", "post_claim_scopes": ["api.read"] } ``` Display `verification_uri` and `user_code` to your user (an RFC 8628 device-flow-style prompt). The registration starts `status: pending` and mints no access token until the ceremony completes. Poll step 3 below with the `claim_token`. `user_code` and `claim_token` both expire after `expires_in` seconds (600s / 10 minutes); call `POST /agent/identity` again to start a fresh ceremony if it lapses. ## 2. Or: claim an existing `anonymous` registration `POST https://uptimeify.io/agent/identity/claim` | Field | Type | Required | Description | | --- | --- | --- | --- | | `claim_token` | string | yes | The `clm_…` returned from an earlier `POST /agent/identity {"type":"anonymous"}` call. | | `email` | string | yes | Email of the user who will authorize the claim. Must contain `@`. | ```bash curl -X POST https://uptimeify.io/agent/identity/claim \ -H 'Content-Type: application/json' \ -d '{"claim_token":"clm_…","email":"user@deinkunde.com"}' ``` ```json { "verification_uri": "https://uptimeify.io/claim?claim_attempt=cat_…", "claim_attempt_token": "cat_…", "expires_in": 600, "interval": 5 } ``` Note what is **absent**: `user_code`. On this path the agent never learns the code, only the signed-in, bound-email user sees it, on the `/claim` page. The registration itself stays `active` and keeps working with its `tools.public` scope throughout: claiming only adds `api.read`, it never revokes anonymous access while the ceremony is pending. Calling this endpoint again before it expires overwrites the prior code/attempt token and resets the 10-minute window. A registration can only be claimed once: a second `POST /agent/identity/claim` (or a `service_auth` claim, which is always pre-bound) after it's already been confirmed returns `409 claimed_or_in_flight`. ## 3. Human consent at `/claim` The bound user must be signed in to Uptimeify as the exact `login_hint` / `email` used above, then either type the `user_code` shown by the agent, or open the `verification_uri` link (which carries `?claim_attempt=…` on the anonymous path). The Uptimeify web app resolves that into the confirmation screen via two session-cookie-authenticated endpoints: these are not called by the agent directly, they exist for completeness of the flow: - `GET /api/agent-claim/context?claim_attempt=`: returns `{ registration_id, agent_type, scope, requested_scope, write_scopes, provider, bound_email, user_code, expires_a…
### Identity assertion (ID-JAG)
URL: https://docs.uptimeify.io/api/agent-auth/identity-assertion
Description: How an agent signed in at a trusted identity provider registers with an ID-JAG, gets a user's approval for read access and selected changes, and how the provider revokes it.
Summary: # Identity assertion (ID-JAG) An agent that already holds an identity from a **trusted identity provider** can register with an **Identity Assertion JWT Authorization Grant** (ID-JAG) instead of `anonymous` or `service_auth`. If the verified email in that assertion belongs to an Uptimeify account, the account holder approves the agent once on the `/claim` page and chooses which changes it may make; from then on the agent re-registers with a fresh ID-JAG and receives its token without another approval. This registration type is **off unless Uptimeify trusts at least one identity provider**. Check the authorization-server metadata: only when `agent_auth.identity_types_supported` contains `"identity_assertion"` are the endpoints on this page live. Otherwise `POST /agent/identity {"type":"identity_assertion"}` returns `400 issuer_not_enabled` and `POST /agent/event/notify` returns `404`. ## 1. Register with an ID-JAG `POST https://uptimeify.io/agent/identity` | Field | Type | Required | Description | | --- | --- | --- | --- | | `type` | string | yes | `"identity_assertion"` | | `assertion_type` | string | yes | `"urn:ietf:params:oauth:token-type:id-jag"` | | `assertion` | string | yes | The ID-JAG issued by your identity provider. | | `scope` | string | no | Space-separated scopes you are asking for, for example `"api.read api.write.monitors"`. Unknown values are ignored; without any known scope the request counts as `"api.read"`. | The ID-JAG must: - be signed by a key from the JWKS of an issuer on Uptimeify's trust list (`iss`), - carry `aud` = `https://uptimeify.io/api/`, an unexpired `exp` and a `jti` that has never been used before (every `jti` is accepted exactly once), - carry `email` with `email_verified: true`, - carry an `auth_time` no older than 3600 seconds; otherwise the answer is `401 login_required` with `max_age: 3600`, and you need a fresh sign-in at your provider. ```bash curl -X POST https://uptimeify.io/agent/identity \ -H 'Content-Type: application/json' \ -d '{"type":"identity_assertion","assertion_type":"urn:ietf:params:oauth:token-type:id-jag","assertion":"","scope":"api.read api.write.monitors"}' ``` The response is one of three outcomes. All of them are sent with `Cache-Control: no-store`. ### Approval needed: `401 interaction_required` The email belongs to an Uptimeify account, and this agent has not been approved yet. ```json { "error": "interaction_required", "registration_id": "reg_…", "claim": { "user_code": "WDJB-MJHT", "verification_uri": "https://uptimeify.io/claim", "verification_uri_complete": "https://uptimeify.io/claim?claim_attempt=cat_…", "expires_in": 600, "interval": 5 }, "claim_token": "clm_…", "requested_scope": "api.read api.write.monitors" } ``` Send your user to `verification_uri_complete`. Signed in as the account with that email, they see what you asked for: read access, and every requested write area as a separate checkbox. **No write area is selected by default**; the user ticks only what the agent really needs. Then poll `POST /oauth2/token` with the claim grant and the `claim_token`, exactly as in [Claim flow, step 4](/api/agent-auth/claim-flow#4-poll-for-completion). The success response carries the approved `scope` and an `identity_assertion` for later exchanges. An email match never links an account on its own: nothing is granted until the signed-in account holder confirms on `/claim`. ### Already approved: `200` with an account assertion The registration for your provider identity (`iss`, `sub`) has been approved before. ```json { "registration_id": "reg_…", "identity_assertion": "", "scope": "api.read api.write.monitors", "token_endpoint": "https://uptimeify.io/oauth2/token" } ``` `scope` is what you asked for if the approval covers it, otherwise everything that was approved. Without a `scope` field you receive everything that was approved. Exchange the `identity_assertion` via the `jwt-bearer` grant as described in [Agent authentication](/api/agent-auth#exchan…
### API Tokens
URL: https://docs.uptimeify.io/api/api-tokens
Description: API tokens allow programmatic access to the Uptimeify API. Tokens are prefixed with wsm_ and can be scoped to a specific customer or organization-wide.
Summary: There are two endpoint scopes: - **Organization tokens** (`/api/organization/tokens`): admin-only, full org access - **Customer tokens** (`/api/customer/tokens`): scoped to accessible customers ## Authentication All examples assume a session cookie (not API tokens, API tokens cannot manage other API tokens): ```bash BASE_URL="https://uptimeify.io" ``` ## Endpoints - [List Organization Tokens](/api/api-tokens/list-organization-tokens) - [Create Organization Token](/api/api-tokens/create-organization-token) - [Delete Organization Token](/api/api-tokens/delete-organization-token) - [List Customer Tokens](/api/api-tokens/list-customer-tokens) - [Create Customer Token](/api/api-tokens/create-customer-token) - [Delete Customer Token](/api/api-tokens/delete-customer-token)
### Create Customer Token
URL: https://docs.uptimeify.io/api/api-tokens/create-customer-token
Description: Creates a new API token scoped to a customer. Restricted users must specify customerId. The full token is returned only once. Store it securely.
Summary: `POST /api/customer/tokens` ## Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `name` | string | Yes | - | Token display name (1-255 chars) | | `expiresInDays` | number | No | null | Days until expiration (1-365). Null = no expiration. | | `customerId` | number | No* | null | Scope token to a specific customer. Required for restricted users. | | `scopes` | string[] | No | null | Restricts the token to these scopes, e.g. `["api.read.monitors"]`. Omit for full access. See [Token Scopes](/api/introduction/token-scopes-organization-vs-customer). Fixed once created. | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/customer/tokens" \ -H "Cookie: $SESSION_COOKIE" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Corp API Token", "customerId": 5, "expiresInDays": 180 }' ``` ## Response ```json { "id": 2, "name": "Acme Corp API Token", "token": "wsm_f7e6d5c4b3a2...", "lastUsedAt": null, "expiresAt": "2026-10-15T08:00:00.000Z", "createdAt": "2026-04-15T08:00:00.000Z", "scopes": null } ``` ## Common errors - `400 invalidRequestBody` when `scopes` is empty, repeats a scope or names an unknown one - `400 Invalid customer ID` when customerId doesn't belong to your organization - `400 customerId is required` when restricted user doesn't specify customerId - `403 Forbidden` when customer is outside user's scope ## Permissions Open to organization admins and to the `readonly` role; `editor` and `responder` are refused with `insufficientPermissions`. A read-only caller is always customer-restricted, so `customerId` is mandatory for it and must name one of its own customers. An organization-wide token (no `customerId`) is not reachable for that role. The issued token inherits the role of the user who created it, so a token minted by a read-only user cannot do more than that user: it may not delete monitors, and it may not change a monitor's ownership class.
### Create Organization Token
URL: https://docs.uptimeify.io/api/api-tokens/create-organization-token
Description: Creates a new API token. The full token is returned only once. Store it securely. Requires admin role.
Summary: `POST /api/organization/tokens` ## Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `name` | string | Yes | - | Token display name (1-255 chars) | | `expiresInDays` | number | No | null | Days until expiration (1-365). Null = no expiration. | | `customerId` | number | No | null | Scope token to a specific customer (must belong to your org) | | `scopes` | string[] | No | null | Restricts the token to these scopes, e.g. `["api.read.monitors"]`. Omit for full access. See [Token Scopes](/api/introduction/token-scopes-organization-vs-customer). Fixed once created. | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/organization/tokens" \ -H "Cookie: $SESSION_COOKIE" \ -H "Content-Type: application/json" \ -d '{ "name": "Production API", "expiresInDays": 90 }' ``` ## Response ```json { "id": 1, "name": "Production API", "token": "wsm_a1b2c3d4e5f6...", "lastUsedAt": null, "expiresAt": "2026-07-15T10:00:00.000Z", "createdAt": "2026-04-15T10:00:00.000Z", "scopes": null } ``` ## Common errors - `400 invalidRequestBody` when `scopes` is empty, repeats a scope or names an unknown one - `400 Invalid customer ID` when customerId doesn't belong to your organization - `401 Unauthorized` when not authenticated - `403 Forbidden` when not an admin
### Delete Customer Token
URL: https://docs.uptimeify.io/api/api-tokens/delete-customer-token
Description: Permanently revokes a customer-scoped API token. Users can only delete tokens within their customer scope.
Summary: `DELETE /api/customer/tokens/:id` ## Example (cURL) ```bash curl -X DELETE "$BASE_URL/api/customer/tokens/2" \ -H "Cookie: $SESSION_COOKIE" ``` ## Response ```json { "success": true } ``` ## Common errors - `403 Forbidden` when the token is outside your customer scope, or when the token is org-scoped (no `customerId`) - `404 Token not found` when the token doesn't exist or belongs to another org ## Permissions Open to organization admins and to the `readonly` role; `editor` and `responder` are refused with `insufficientPermissions`. A customer-restricted caller may only revoke tokens bound to its own customers: an organization-wide token (no `customerId`) is refused outright. `api_token` records no issuer for tokens created before 04.09.2026, so a read-only user can revoke a customer-scoped token that an admin issued for the same customer.
### Delete Organization Token
URL: https://docs.uptimeify.io/api/api-tokens/delete-organization-token
Description: Permanently revokes an API token. Requires admin role.
Summary: `DELETE /api/organization/tokens/:id` ## Example (cURL) ```bash curl -X DELETE "$BASE_URL/api/organization/tokens/1" \ -H "Cookie: $SESSION_COOKIE" ``` ## Response ```json { "success": true } ``` ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` when not an admin - `404 Token not found` when the token doesn't exist or belongs to another org
### List Customer Tokens
URL: https://docs.uptimeify.io/api/api-tokens/list-customer-tokens
Description: Returns API tokens visible to the current user. Restricted users see only their customer-scoped tokens; admins see all tokens. Tokens are masked: only the first 8 characters are shown.
Summary: `GET /api/customer/tokens` ## Query Parameters | Parameter | Type | Default | Description | |---|---|---|---| | `envelope` | string | none | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ## Example (cURL) ```bash curl -X GET "$BASE_URL/api/customer/tokens?envelope=items" \ -H "Cookie: $SESSION_COOKIE" \ -H "Accept: application/json" ``` ## Response ```json { "items": [ { "id": 2, "organizationId": 1, "name": "Customer Scoped Token", "customerId": 5, "customerName": "Acme Corp", "lastUsedAt": null, "expiresAt": null, "createdAt": "2026-02-01T08:00:00.000Z", "tokenHint": "wsm_f7e6d5..." } ], "total": 1, "page": 1, "perPage": 1 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form (a bare array of the same items), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` when user lacks read access
### List Organization Tokens
URL: https://docs.uptimeify.io/api/api-tokens/list-organization-tokens
Description: Returns all API tokens for the organization. Tokens are masked: only the first 8 characters are shown. Requires admin role.
Summary: `GET /api/organization/tokens` ## Query Parameters | Parameter | Type | Default | Description | |---|---|---|---| | `envelope` | string | none | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ## Example (cURL) ```bash curl -X GET "$BASE_URL/api/organization/tokens?envelope=items" \ -H "Cookie: $SESSION_COOKIE" \ -H "Accept: application/json" ``` ## Response ```json { "items": [ { "id": 1, "organizationId": 1, "name": "Production API", "customerId": null, "customerName": null, "lastUsedAt": "2026-04-01T12:00:00.000Z", "expiresAt": null, "createdAt": "2026-01-15T10:00:00.000Z", "tokenHint": "wsm_a1b2c..." } ], "total": 1, "page": 1, "perPage": 1 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form (a bare array of the same items), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` when not an admin
### Auth & Session
URL: https://docs.uptimeify.io/api/auth
Description: Manage your current user session and retrieve profile information.
Summary: ## Endpoints - [Get Current User](/api/auth/get-current-user)
### Get Current User
URL: https://docs.uptimeify.io/api/auth/get-current-user
Description: Returns a reduced view of the currently authenticated user and their session.
Summary: `GET /api/auth/get-session` ## Request ```http GET /api/auth/get-session HTTP/1.1 ``` This endpoint returns a public-safe session payload. For integrations, use API tokens (`Authorization: Bearer wsm_...`) with the REST endpoints under `/api/**`. Sensitive internal app fields such as `email`, `role`, `language`, `isGlobalAdmin`, `isGlobalSupporter`, `emailVerified`, `image`, and platform-admin customer context are intentionally not included. ## Response ```json { "user": { "id": "user_12345", "name": "Max Mustermann", "firstName": "Max", "lastName": "Mustermann", "organizationId": 1, "organizationStatus": "active", "isActive": true, "createdAt": "2026-03-31T15:50:49.030Z", "updatedAt": "2026-03-31T15:50:49.030Z" }, "session": { "userId": "user_12345", "expiresAt": "2027-03-31T15:58:26.618Z", "token": "session-token-value" } } ```
### Change Requests
URL: https://docs.uptimeify.io/api/change-requests
Description: How customers request changes to managed monitors and how organizations resolve them.
Summary: Monitors with `managementType: managed` are read-only for customer-scoped users (see [Managed vs. Self-Service Monitors](/monitoring/managed-vs-self-service)). Instead of editing directly, a customer opens a **change request** against the monitor; the organization reviews it in its inbox and accepts or rejects it. A change request has a `kind`: | Kind | Meaning | Effect on accept | |---|---|---| | `change` | Free-text change wish for a managed monitor | None automatic: the org applies the change manually | | `request_managed` | The customer asks the org to take over responsibility for a monitor or a status page | The monitor or status page is flipped to `managed` automatically | Endpoints: - [Create Change Request](/api/change-requests/create-change-request): `POST /api/monitors/:monitorType/:monitorId/change-requests` (customer or org) - [Create Status Page Change Request](/api/change-requests/create-status-page-change-request): `POST /api/status-pages/:id/change-requests` (customer or org, since 30 October 2026) - [List Change Requests](/api/change-requests/list-change-requests): `GET /api/change-requests` (org admins) - [Resolve Change Request](/api/change-requests/resolve-change-request): `PATCH /api/change-requests/:id` (org admins) Status pages with `managementType: managed` work the same way (see [Who may change a status page](/api/status-pages#who-may-change-a-status-page)); their requests carry `monitorType: status_page`. Open requests are limited to **10 per customer** across all monitor types and status pages; further creates return `429` (`tooManyOpenRequests`).
### Create Change Request
URL: https://docs.uptimeify.io/api/change-requests/create-change-request
Description: Opens a change request against any monitor (all monitor types).
Summary: `POST /api/monitors/:monitorType/:monitorId/change-requests` Read access to the monitor is sufficient. The typical caller is a customer portal user who *lacks* write access to a `managed` monitor. ## Path parameters | Parameter | Description | |---|---| | `monitorType` | One of `website`, `dns`, `icmp`, `smtp`, `ssh`, `ftp`, `imap_pop`, `domain`, `dnsbl` | | `monitorId` | Numeric ID of the monitor | ## Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `kind` | string | No | `change` | `change` (free-text wish) or `request_managed` (ask the org to take the monitor over) | | `message` | string | Yes | - | The request text (1-2000 chars) | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/monitors/website/103/change-requests" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "kind": "change", "message": "Please lower the check interval to 1 minute." }' ``` ## Response ```json { "id": 12, "status": "open" } ``` ## Common errors - `400 Invalid monitor type` (`invalidMonitorType`) when `monitorType` is not one of the supported types - `400 Invalid monitor identifier` when `monitorId` is not a positive integer - `401 Unauthorized` when you are not logged in - `403 Forbidden` / `404 Not found` when the monitor is outside your scope - `403 Forbidden` with `data.code` `authorizingUserUnresolved` when the call arrives over an agent session whose authorizing human can no longer be resolved. `requested_by` is `NOT NULL` and points at a real user, so there is no value to fall back to and no request is created. Re-authorize the connection, or open the request from a session that belongs to a person. - `429 Too many open requests` (`tooManyOpenRequests`) when the customer already has 10 open requests
### Create Status Page Change Request
URL: https://docs.uptimeify.io/api/change-requests/create-status-page-change-request
Description: Asks the organization for a change to a status page, or to take a self_service page over. Read access is enough.
Summary: `POST /api/status-pages/:id/change-requests` Read access to the status page is enough: organization roles `admin`, `editor` and `readonly`, customer users (also with the role `readonly`) and API tokens, each within their customer scope. The typical caller is a customer user who may not change a `managed` page (see [Who may change a status page](/api/status-pages#who-may-change-a-status-page)) and asks the organization for a change instead. With `kind: request_managed` a customer asks the organization to take a `self_service` page over. The request lands in the same inbox as monitor change requests: [List Change Requests](/api/change-requests/list-change-requests) returns it with `monitorType: "status_page"`, `monitorId` = the status page id and `monitorName` = the page name, and [Resolve Change Request](/api/change-requests/resolve-change-request) accepts or rejects it. Accepting a `request_managed` request sets the page to `managementType: managed`. ## Path parameters | Parameter | Description | |---|---| | `id` | Status page ID or `publicId` (UUID) | ## Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `kind` | string | No | `change` | `change` (free-text wish) or `request_managed` (ask the organization to take the page over) | | `message` | string | Yes | - | The request text (1 to 2000 characters) | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/status-pages/db58058e-4b58-4d97-a314-3bb8e279a182/change-requests" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "kind": "change", "message": "Please add the new checkout API as a component." }' ``` ## Response `201 Created` ```json { "id": 14, "status": "open" } ``` Open requests are limited to **10 per customer** across all types (monitors and status pages). ## Common errors - `400 Bad Request` (`invalidRequestBody`) when `kind` is not `change` or `request_managed`, or `message` is empty or longer than 2000 characters - `400 Bad Request` (`statusPageHasNoCustomer`) when the page has no customer (`customerId: null`): there is no customer who could ask, so such a page takes no change requests - `400 Invalid Status page identifier` when `id` is neither a numeric ID nor a UUID - `401 Unauthorized` when you are not logged in - `403 Forbidden` (`forbidden`) when your role may not read status pages, the page belongs to a customer outside your scope, or a customer-bound caller names a page without a customer - `403 Forbidden` (`authorizingUserUnresolved`) when the call arrives over an agent session whose authorizing human can no longer be resolved. Every request records the person who asked, so no request is created. Re-authorize the connection, or open the request from a session that belongs to a person. - `403 Forbidden` (`statusPagesModuleDisabled`) when the status pages module is not active for your organization - `404 Status page not found` when no status page has that ID (no `data.code`), or (`statusPageNotFound`) when it belongs to another organization - `429 Too many open requests` (`tooManyOpenRequests`) when the customer already has 10 open requests
### List Change Requests
URL: https://docs.uptimeify.io/api/change-requests/list-change-requests
Description: Lists the organization's change-request inbox.
Summary: `GET /api/change-requests` Organization write access required (organization admin or global admin). Results are strictly scoped to the caller's organization. ## Query parameters | Parameter | Type | Required | Default | Description | |---|---|---|---|---| | `status` | string | No | `open` | `open`, `accepted`, or `rejected` | ## Query Parameters | Parameter | Type | Default | Description | |---|---|---|---| | `envelope` | string | none | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl "$BASE_URL/api/change-requests?status=open&envelope=items" \ -H "Authorization: Bearer $TOKEN" ``` ## Response Newest first. `monitorName` is resolved per monitor type; `websiteId` is a legacy field populated only for website monitors. `monitorType` can also be `status_page` (since 30 October 2026, from [Create Status Page Change Request](/api/change-requests/create-status-page-change-request)): `monitorId` is then the status page id, `monitorName` the page name and `websiteId` `null`. ```json { "items": [ { "id": 12, "monitorType": "website", "monitorId": 103, "websiteId": 103, "customerId": 101, "customerName": "Customer A GmbH", "monitorName": "New Landing Page", "requestedBy": "usr_123", "kind": "change", "message": "Please lower the check interval to 1 minute.", "status": "open", "resolvedBy": null, "resolvedAt": null, "createdAt": "2026-07-09T10:00:00.000Z" } ], "total": 1, "page": 1, "perPage": 1 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form (a bare array of the same items), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. ## Common errors - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you are not an organization admin
### Resolve Change Request
URL: https://docs.uptimeify.io/api/change-requests/resolve-change-request
Description: Accepts or rejects an open change request.
Summary: `PATCH /api/change-requests/:id` Organization write access required. The status transition is atomic: under concurrent resolves only one caller wins; the loser receives `409`. Accepting a request with `kind: request_managed` additionally flips the target monitor to `managementType: managed` (dispatched to the correct table for the monitor's type). For `monitorType: status_page` (since 30 October 2026) it sets the status page to `managementType: managed`. ## Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `status` | string | Yes | `accepted` or `rejected` | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PATCH "$BASE_URL/api/change-requests/12" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "accepted" }' ``` ## Response ```json { "id": 12, "status": "accepted" } ``` ## Common errors - `400 Invalid change-request identifier` - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you are not an organization admin - `404 Change request not found` (`changeRequestNotFound`) when the request does not exist or belongs to another organization. Until 20.10.2026 another organization's request answered `403`. - `409 Change request already resolved` when the request is no longer `open`
### Custom Fields
URL: https://docs.uptimeify.io/api/custom-fields
Description: Define custom metadata fields that can be attached to customers and websites. Custom fields support text, select, and multi-select types.
Summary: ## Authentication All examples assume a bearer token: ```bash BASE_URL="https://uptimeify.io" TOKEN="" ``` ## Endpoints - [List Custom Fields](/api/custom-fields/list-custom-fields) - [Get Custom Field](/api/custom-fields/get-custom-field) - [Create Custom Field](/api/custom-fields/create-custom-field) - [Update Custom Field](/api/custom-fields/update-custom-field) - [Delete Custom Field](/api/custom-fields/delete-custom-field)
### Create Custom Field
URL: https://docs.uptimeify.io/api/custom-fields/create-custom-field
Description: Creates a new custom field definition.
Summary: `POST /api/custom-fields` Requires the `admin` role (or a global admin). Editors and read-only users receive `403`. ## Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `organizationId` | number | No | from session | Must match your own organization if given | | `name` | string | Yes | - | Display name, 1 to 100 characters | | `fieldKey` | string | No | auto from name | Unique key, max 100 characters (auto-normalized: lowercase, non-alphanumeric → `_`) | | `fieldType` | string | No | `text` | One of `text`, `number`, `email`, `url`, `select` | | `isRequired` | boolean | No | false | Whether the field is required | | `displayOrder` | number | No | 0 | Sort order, integer 0 to 10000 | | `options` | string[] | No | `[]` | Options for the `select` type, max 50 entries of max 100 characters each | | `placeholder` | string\|null | No | null | Placeholder text, max 200 characters | | `helpText` | string\|null | No | null | Help text below the field, max 500 characters | | `showInTable` | boolean | No | true | Show in table views | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/custom-fields" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "organizationId": 1, "name": "Environment", "fieldType": "select", "options": ["production", "staging", "development"], "isRequired": true, "showInTable": true }' ``` ## Common errors - `400 Bad Request` when the body fails validation (unknown `fieldType`, `name` missing or over 100 characters, more than 50 `options`) - `403 Forbidden` when your role is not `admin`, or when `organizationId` names another organization - `409 Conflict` (`customFieldAlreadyExists`) when an active field with this `fieldKey` already exists for the organization. A deleted (deactivated) field with the same key is reactivated with the values from the body instead; values already stored on customers under the key stay as they are. ## Response Returns the created custom field object. See [Error Codes](/api/error-codes-and-known-pitfalls) for error responses.
### Delete Custom Field
URL: https://docs.uptimeify.io/api/custom-fields/delete-custom-field
Description: Soft-deletes a custom field (sets isActive: false).
Summary: `DELETE /api/custom-fields/:id` Requires the `admin` role (or a global admin). Editors and read-only users receive `403`. ## Example (cURL) ```bash curl -X DELETE "$BASE_URL/api/custom-fields/1" \ -H "Authorization: Bearer $TOKEN" ``` ## Common errors - `403 Forbidden` when your role is not `admin` - `404 Not Found` when the field does not exist in your organization ## Response ```json { "success": true, "message": "Custom field deleted successfully" } ```
### Get Custom Field
URL: https://docs.uptimeify.io/api/custom-fields/get-custom-field
Description: Returns one active custom field definition of your organization, in the same shape as an entry of List Custom Fields.
Summary: `GET /api/custom-fields/{id}` ## Access Any member of the organization. Only definitions of your own organization that are active are returned; a deleted (inactive) field answers `404`. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/custom-fields/7" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response `200 OK` ```json { "id": 7, "organizationId": 10, "name": "Contract number", "fieldKey": "contract_number", "fieldType": "text", "isRequired": false, "displayOrder": 1, "options": null, "placeholder": "e.g. C-2026-001", "helpText": null, "showInTable": true, "isActive": true, "createdAt": "2026-06-01T08:00:00.000Z", "updatedAt": "2026-06-01T08:00:00.000Z" } ``` ## Common errors - `400 Bad Request` (`fieldIdRequired`) when the id is not a positive number - `401 Unauthorized` when you are not logged in - `404 Not Found` (`customFieldNotFound`) when the field does not exist, is inactive or belongs to another organization
### List Custom Fields
URL: https://docs.uptimeify.io/api/custom-fields/list-custom-fields
Description: Returns all active custom field definitions for the organization.
Summary: `GET /api/custom-fields` ## Query Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `organizationId` | number | session org | Override organization scope | | `envelope` | string | none | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ## Example (cURL) ```bash curl -X GET "$BASE_URL/api/custom-fields?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "items": [ { "id": 1, "organizationId": 1, "name": "Data Center", "fieldKey": "data_center", "fieldType": "text", "isRequired": false, "displayOrder": 0, "options": [], "placeholder": "e.g. fsn1", "helpText": "Primary data center location", "showInTable": true, "isActive": true, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } ], "total": 1, "page": 1, "perPage": 1 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form (a bare array of the same items), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. Only active fields (`isActive: true`) are returned, ordered by `displayOrder`.
### Update Custom Field
URL: https://docs.uptimeify.io/api/custom-fields/update-custom-field
Description: Updates a custom field definition. All fields are optional.
Summary: `PATCH /api/custom-fields/:id` Requires the `admin` role (or a global admin). Editors and read-only users receive `403`. ## Request Body (all optional) | Field | Type | Description | |-------|------|-------------| | `name` | string | Display name, 1 to 100 characters | | `fieldType` | string | One of `text`, `number`, `email`, `url`, `select` | | `isRequired` | boolean | Whether the field is required | | `displayOrder` | number | Sort order, integer 0 to 10000 | | `options` | string[] | Options for the `select` type, max 50 entries of max 100 characters each | | `placeholder` | string\|null | Placeholder text, max 200 characters | | `helpText` | string\|null | Help text, max 500 characters | | `showInTable` | boolean | Show in table views | | `isActive` | boolean | Soft delete (set to false) | ## Example (cURL) ```bash curl -X PATCH "$BASE_URL/api/custom-fields/1" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Environment", "options": ["production", "staging", "development", "qa"] }' ``` ## Common errors - `400 Bad Request` when the body fails validation (unknown `fieldType`, `name` over 100 characters, more than 50 `options`) - `403 Forbidden` when your role is not `admin` - `404 Not Found` when the field does not exist in your organization ## Response Returns the updated custom field object. See [Error Codes](/api/error-codes-and-known-pitfalls) for error responses.
### Customer Management
URL: https://docs.uptimeify.io/api/customers
Description: Path-based customer endpoints use customerPublicId UUIDs.
Summary: ## Endpoints - [List Customers](/api/customers/list-customers) - [Create Customer](/api/customers/create-customer) - [Get Customer Details](/api/customers/get-customer-details) - [Update Customer](/api/customers/update-customer) - [Change Package](/api/customers/change-package) - [SMS Usage](/api/customers/sms-usage)
### Bulk Actions
URL: https://docs.uptimeify.io/api/customers/bulk-actions
Description: Applies one action to many customers at once, for multi-select workflows.
Summary: `POST /api/customers/bulk` Applies a single action to a list of customer ids. Each id is processed independently: one conflicting or missing customer does not abort the rest. The response is always **`200 OK`**, even when some ids failed, so check `failed` rather than relying on the HTTP status alone. ## Authentication ```bash BASE_URL="https://uptimeify.io" TOKEN="" ``` ## Request Body ```json { "ids": [101, 102, 103], "action": "reports", "payload": { "enabled": true } } ``` | Field | Type | Required | Description | |-------|------|----------|--------------| | `ids` | number[] | yes | Customer ids (the numeric `id`, not `publicId`). Non-empty, at most **200** entries, positive integers, no duplicates. | | `action` | string | yes | One of `reports`, `activate`, `deactivate`, `delete`, `package`. | | `payload` | object | depends on `action` | Required for `reports` and `package` (see below). Optional for `delete` (`userAction`). Ignored for `activate`, `deactivate`. | ### Actions | Action | Effect | `payload` | |--------|--------|-----------| | `reports` | Sets `monthlyReportsEnabled` on each customer. | `{ "enabled": boolean }` (required) | | `activate` | Sets the customer's status to `active` (a no-op if already active) and cascades monitor statuses accordingly. | none | | `deactivate` | Sets the customer's status to `inactive` (a no-op if already inactive) and cascades monitor statuses accordingly. | none | | `delete` | Hard-deletes the customer. Monitors and check history are removed with it via cascade. Users assigned **only** to this customer are deactivated or deleted, see [Delete Customer](/api/customers/delete-customer). **Not reversible.** | `{ "userAction": "deactivate" \| "delete" }` (optional, default `deactivate`) | | `package` | Reassigns the customer to a different package by id. | `{ "packageId": number }` (required) | `package` only accepts a numeric `packageId` that belongs to **the target customer's own organization**. For every caller except a global admin that is the same thing as your own organization, because you can only address customers inside it. A global admin addressing customers across organizations needs a `packageId` from each customer's own organization; one belonging to a different organization is rejected with `invalidPackageType`. Unlike [Update Customer](/api/customers/update-customer), it does not resolve a legacy `packageType` string or display name, since guessing which package was meant across up to 200 rows at once is not something the bulk endpoint does; look up the id from [List Package Configs](/api/organization/list-package-configs) first. `payload.enabled`, `payload.packageId` and `payload.userAction` are validated **once, up front**, before any customer is touched. A malformed payload fails the whole request with `400 invalidRequestBody`; it never turns into 200 identical per-id failures. ## Example Request ```bash curl -X POST "$BASE_URL/api/customers/bulk" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "ids": [101, 102, 103], "action": "reports", "payload": { "enabled": true } }' ``` ## Example Response (partial result) ```json { "ok": [101, 103], "failed": [ { "id": 102, "reason": "customerNotFound" } ] } ``` `ok` lists the ids that were updated. `failed` lists the ids that were not, each with a `reason` string. Render the split (for example "2 of 3 updated"), never a blanket success from the fact that the request itself returned `200`. ## Common Errors These fail the **whole request** before any customer is touched: - `401 unauthorized` you are not logged in - `403 forbidden` your role is `readonly`, or you are a global-supporter (both are read-only for this endpoint) - `403 forbidden` `action: "delete"` and you are neither an organization admin, an editor nor a global admin (for example a responder). Like `DELETE /api/customers/:id`, admins and editors may delete customers; an editor assigned to customers deletes only those…
### Change Package
URL: https://docs.uptimeify.io/api/customers/change-package
Description: Changes the customer's package assignment.
Summary: `PATCH /api/customers/:customerPublicId` This uses the same endpoint as [Update Customer](/api/customers/update-customer). You usually send `packageId`. Legacy `packageType` values are still accepted for backward compatibility, but they must resolve to a package the organization actually has: a package key or a package display name. An unknown value is rejected with `400` and `data.code` `invalidPackageType`. ## Authentication ```bash BASE_URL="https://uptimeify.io" TOKEN="" ``` ## Request Body ```json { "packageId": 12 } ``` ## Example Request ```bash curl -X PATCH "$BASE_URL/api/customers/6bfec6f6-245a-47ce-843b-157d97d56f88" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "packageId": 12 }' ``` ## Example Response ```json { "id": 101, "publicId": "6bfec6f6-245a-47ce-843b-157d97d56f88", "organizationId": 1, "name": "Customer A GmbH", "email": "contact@customer-a.de", "notificationPhoneNumber": null, "notificationEmail": null, "packageId": 12, "status": "active", "monthlyReportsEnabled": true, "customFields": {}, "notificationChannels": null, "notificationTargets": null, "updatedAt": "2026-02-26T19:37:00.000Z" } ``` ## Common Errors - `400` Invalid Customer identifier - `400` Invalid packageId / packageType for this organization (`data.code`: `invalidPackageType`) - `401` Unauthorized - `403` Forbidden / Organization ID not found - `404` Customer not found - `500` Failed to update customer
### Create Customer
URL: https://docs.uptimeify.io/api/customers/create-customer
Description: Creates a new customer and assigns an organization-defined package via packageType.
Summary: `POST /api/customers` ## Authentication This endpoint requires authentication. ```bash BASE_URL="https://uptimeify.io" TOKEN="wsm_" ``` ## Request Body ```json { "name": "Customer Name", "email": "customer@deinkunde.com", "packageType": "business", // use the configured packageType or displayName for the organization "organizationId": 1, // optional (required only for global admins) "status": "active", // optional, Default: active "monthlyReportsEnabled": true, // optional, defaults to the package's monthlyReportsDefault "companyName": "Nordwind ApS", "emailLanguage": "en", // optional: de, en or da; default: same as the organization "customFields": { ... } // optional } ``` Notes: - `packageType` can contain the configured package key or the package display name of the organization. Known aliases such as `aquisition_test` are normalized automatically. - `monthlyReportsEnabled` is optional. Omit it and the new customer is seeded from the assigned package's `monthlyReportsDefault` (see [Upsert Package Config](/api/organization/upsert-package-config)); if the organization has no config row for that package, it falls back to `true`. An explicit value in the request always wins, the customer field alone decides whether a report is sent. - `companyName` is optional: the customer's company name, shown as "Company" on the customer page. Empty or `null` clears it. - `emailLanguage` is optional: `de`, `en` or `da`, the language of the e-mails and text messages this customer receives (alerts, reports, status pages). Omit it or send `null` and the customer follows the organization's language. Any other value is rejected with `400`. It can be changed later with [Update Customer](/api/customers/update-customer). - If no configured package matches, the request is rejected with `400 Bad Request`. - `notificationPhoneNumber` is optional: the number alert SMS for this customer go to. It must be in international format (`+` and country calling code) and from the EU/EEA, Switzerland or the UK, otherwise the request is rejected with `400 Bad Request` (`data.code`: `smsCountryNotAllowed`). - For non-global-admin users, `organizationId` is derived from your session/token and must not be overridden. - For global admins, `organizationId` must be provided explicitly. - Creating a customer is an organization-wide operation: it requires an **unrestricted customer scope**, not just a role. `readonly` users, `editor` users assigned to specific customers and customer-scoped tokens receive `403` with `data.code: customerScopedTokenForbidden` (see [Roles and the customer scope](/api/introduction/token-scopes-organization-vs-customer)). Organization-wide editors and admins may create customers. ## Ownership & permission overrides (optional) These fields control the customer's [managed vs. self-service](/monitoring/managed-vs-self-service) permissions and channel-type policy. They are **organization-write gated**: only organization admins (or global admins) can set them. A non-admin caller's values are ignored and the schema defaults apply. `null` (or omitting the field) means *inherit from the customer's package config*. | Field | Type | Default | Description | |-------|------|---------|-------------| | `allowSelfService` | boolean\|null | null (inherit) | Whether the customer may create and manage `self_service` monitors | | `maxSelfServiceUrls` | number\|null | null (inherit) | Cap on the customer's **total** `self_service` monitors across all monitor types | | `canEditManaged` | boolean | false | Exception: lets this customer edit `managed` monitors (class flips stay org-only). Grants are written to the audit log. | | `enableEmailAlerts` | boolean\|null | null (inherit) | Whether your organization's own email channels alert about this customer (null = follow the package). Never affects channels the customer sets up themselves | | `enableSmsAlerts` | boolean\|null | null (inherit) | Whether your organization's own SMS channels alert about th…
### Delete Customer
URL: https://docs.uptimeify.io/api/customers/delete-customer
Description: Permanently deletes a customer and deactivates or deletes the users assigned only to it.
Summary: `DELETE /api/customers/:customerPublicId` Permanently deletes a customer. Its monitors, check history, incidents, reports and screenshots are removed with it. **This cannot be undone.** Organization admins, editors and global admins may delete customers. Readonly users, global supporters, responders and customer-scoped API tokens receive `403`. An editor assigned to specific customers can delete only those customers (any other id answers `404`); an editor without customer assignments can delete every customer of the organization. Two things stay with admins. Only an admin may send `userAction=delete`; an editor gets `403` with `customerUserDeleteAdminOnly` and uses the default `deactivate`. An editor assigned to customers cannot delete the last of them: they would end up without a customer and deactivate their own account, so the request answers `409` with `cannotDeleteOwnLastCustomer`. Both checks run before anything is deleted. ## Users of the customer Users who have access **only** to this customer cannot keep their account without one. One of two things always happens to them, chosen with the `userAction` query parameter: | `userAction` | Effect | |--------------|--------| | `deactivate` (default) | The users are deactivated. They can no longer use the dashboard or the API and can be reactivated later with [Update User](/api/users/update-user). | | `delete` | The users are deleted permanently. | Users who also have access to other customers keep their account and only lose access to the deleted customer. There is no option to keep users without a customer. ## Authentication ```bash BASE_URL="https://uptimeify.io" TOKEN="wsm_" ``` ## Example Request ```bash curl -X DELETE "$BASE_URL/api/customers/6bfec6f6-245a-47ce-843b-157d97d56f88?userAction=delete" \ -H "Authorization: Bearer $TOKEN" ``` ## Example Response ```json { "success": true, "message": "Customer deleted successfully", "userAction": "delete", "affectedUsers": 1 } ``` `affectedUsers` is the number of users that were deactivated or deleted. ## Common errors - `400 Bad Request` with `data.code: "invalidUserAction"` when `userAction` is neither `deactivate` nor `delete`. Nothing is deleted. - `403 Forbidden` with `data.code: "forbidden"` when the caller is neither an organization admin nor an editor (readonly, global supporter, responder) or uses a customer-scoped token - `403 Forbidden` with `data.code: "customerUserDeleteAdminOnly"` when an editor sends `userAction=delete`. Nothing is deleted. - `409 Conflict` with `data.code: "cannotDeleteOwnLastCustomer"` when an editor assigned to customers would delete the last of them. Nothing is deleted. - `404 Not Found` with `data.code: "customerNotFound"` when the customer does not exist in your organization
### Get Customer Details
URL: https://docs.uptimeify.io/api/customers/get-customer-details
Description: Returns details of a specific customer.
Summary: `GET /api/customers/:customerPublicId` `packageDisplayName` is the configured display label of the assigned organization package. It is not a normalized global enum and may contain organization-specific names such as `aquisition_test`. ## Response ```json { "id": 101, "publicId": "6bfec6f6-245a-47ce-843b-157d97d56f88", "organizationId": 1, "name": "Customer A GmbH", "email": "contact@customer-a.de", "notificationPhoneNumber": "+491701234567", "notificationEmail": "alerts@customer-a.de", "packageId": 3, "packageType": "growth", "packageDisplayName": "Growth", "status": "active", "customFields": { "internalReference": "KD-999" }, "monthlyReportsEnabled": true, "companyName": "Nordwind ApS", "emailLanguage": "en", "notificationChannels": null, "notificationTargets": null, "notificationRules": null, "smsUsageCurrentMonth": 0, "allowSelfService": null, "maxSelfServiceUrls": null, "canEditManaged": false, "enableEmailAlerts": null, "enableSmsAlerts": null, "enableWebhookAlerts": null, "enableIntegrationAlerts": null, "enablePostRequestEscalation": null, "updatedAt": "2023-05-15T10:00:00Z", "createdAt": "2023-05-15T10:00:00Z" } ``` **`packageType` and permission overrides:** `packageType` is the raw package key of the customer (the value `packageType` in the request body resolves to). The permission overrides (`allowSelfService`, `maxSelfServiceUrls`, `canEditManaged`, `enableEmailAlerts`, `enableSmsAlerts`, `enableWebhookAlerts`, `enableIntegrationAlerts`, `enablePostRequestEscalation`; `null` = inherit from the package) are present only for callers that may also write them: an organization admin with an unrestricted customer scope. For a customer-bound token, any user without the admin role (`editor`, `readonly`), or a global supporter the fields are left out of the response. ## Common Errors - `400` Invalid Customer identifier - `401` Unauthorized - `404` Customer not found (`customerNotFound`): the customer does not exist, belongs to another organization or lies outside your customer scope. Until 20.10.2026 the last case answered `403`.
### List Customers
URL: https://docs.uptimeify.io/api/customers/list-customers
Description: Lists all customers of the organization.
Summary: `GET /api/customers` ## Query Parameters - `organizationId` (required): The ID of the organization. - `fields` (optional): Set to `minimal` to return a lightweight shape containing only `id`, `publicId`, `name`, `status`, and `customFields`. The monitor counts and package details are omitted, and the response is much smaller. Useful for populating pickers/dropdowns. ## Response With `fields=minimal`: ```json [ { "id": 101, "publicId": "cus_9f3a…", "name": "Customer A GmbH", "status": "active", "customFields": { "region": "EU" } } ] ``` Default response: ```json [ { "id": 101, "organizationId": 1, "name": "Customer A GmbH", "email": "contact@customer-a.de", "packageId": 4, "packageDisplayName": "Business", "status": "active", "cancellationDate": null, "notificationEmail": "alerts@customer-a.de", "createdAt": "2023-05-15T10:00:00Z", "statusPageCount": 2 }, { "id": 102, "organizationId": 1, "name": "StartUp XY", "email": "info@startup-xy.com", "packageId": 1, "packageDisplayName": "Essential", "status": "marked_for_cancellation", "cancellationDate": "2024-12-31T23:59:59Z", "createdAt": "2023-06-20T14:30:00Z", "statusPageCount": 0 } ] ``` **Status pages:** every customer carries `statusPageCount`, the number of its status pages, published or not (the same count the package's status page limit is enforced against). In the paged form it is sortable with `sortBy=statusPageCount`, and with `summary=1` each row's `summary` adds `packageMaxStatusPages`, the status pages per customer allowed by its package (`null` = unlimited). **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }` and is always paged: `page` defaults to 1, `perPage` to 10 (at most 100), with the same filters and sorting as with `page` (`search`, `status`, `packageTypes`, `sortBy`, `sortOrder`, `summary`); `packageOptions` is left out. With `fields=minimal` every customer arrives in the short form as a single page. Without the parameter the endpoint still answers the current form, which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. Note: The list response intentionally no longer exposes the raw `packageType`. Use `packageDisplayName` for display and `packageId` for technical mapping. `packageDisplayName` comes from the assigned organization package config and may therefore be organization-specific.
### SMS Usage
URL: https://docs.uptimeify.io/api/customers/sms-usage
Description: Returns the SMS usage for the current calendar month across all customers of the organization, sorted by usage descending.
Summary: `GET /api/customers/sms-usage` ## Query Parameters - `organizationId` (required): The ID of the organization. - `envelope` (optional): `items` answers the list form described below. ## Response ```json { "total": 47, "smsTotalCurrentMonth": 47, "customers": [ { "publicId": "6bfec6f6-245a-47ce-843b-157d97d56f88", "name": "Customer A GmbH", "status": "active", "smsUsageCurrentMonth": 32 }, { "publicId": "9a1c3d2e-8f4b-42a1-b7c9-3e5f12d84a90", "name": "StartUp XY", "status": "active", "smsUsageCurrentMonth": 15 }, { "publicId": "2d7e5f1a-6c3b-4d9e-a2f8-1b4c7e9d3a56", "name": "Inactive Corp", "status": "inactive", "smsUsageCurrentMonth": 0 } ] } ``` ### Fields | Field | Type | Description | |---|---|---| | `total` | `number` | Deprecated, removed on 2027-01-18: use `smsTotalCurrentMonth`. Same value. | | `smsTotalCurrentMonth` | `number` | Sum of `smsUsageCurrentMonth` across all returned customers. | | `customers[].publicId` | `string` | Customer UUID. | | `customers[].name` | `string` | Customer display name. | | `customers[].status` | `string` | Customer status: `active`, `inactive`, `marked_for_cancellation`, or `cancelled`. | | `customers[].smsUsageCurrentMonth` | `number` | Number of SMS sent for this customer in the current month. Resets at the start of each calendar month. | ## List form (`?envelope=items`) With `?envelope=items` the endpoint answers the standard list form. It becomes the default on 2027-01-18; the form above is deprecated. ```json { "items": [ { "publicId": "6bfec6f6-245a-47ce-843b-157d97d56f88", "name": "Customer A GmbH", "status": "active", "smsUsageCurrentMonth": 32 } ], "total": 1, "page": 1, "perPage": 1, "smsTotalCurrentMonth": 32 } ``` Here `total` is the number of customers, not the SMS sum; the sum is `smsTotalCurrentMonth`. All customers come in one page. ## Notes - The usage counter `smsUsageCurrentMonth` resets at the beginning of each calendar month. - Customers with zero usage are included in the response. - Results are ordered by `smsUsageCurrentMonth` descending (highest usage first). - For the complete SMS quota and overage details of the entire organization, see the billing overview. ## Common Errors - `400` Organization ID required - `401` Unauthorized - `403` Forbidden
### Update Customer
URL: https://docs.uptimeify.io/api/customers/update-customer
Description: Updates customer details.
Summary: `PATCH /api/customers/:customerPublicId` ## Authentication ```bash BASE_URL="https://uptimeify.io" TOKEN="" ``` ## Request Body All fields are optional. Omitted fields keep their current values. ```json { "name": "New Name", "email": "new@deinkunde.com", "status": "active", "packageType": "business", // configured packageType or displayName for the organization "notificationEmail": "alerts@customer-a.de", "notificationPhoneNumber": "+491701234567", "monthlyReportsEnabled": true, "companyName": "Nordwind ApS", "emailLanguage": "en", "customFields": { "internalReference": "KD-999" } } ``` Notes: - `packageType` can contain the configured package key or the package display name of the organization. Known aliases such as `aquisition_test` are normalized automatically. A value that resolves to no package of this organization is rejected with `400` and `data.code` `invalidPackageType`; it is no longer stored as-is. - `companyName` is optional: the customer's company name, shown as "Company" on the customer page. Empty or `null` clears it. - `emailLanguage` sets the language of the e-mails this customer receives (alerts, reports, status pages): `de`, `en` or `da`. `null` returns it to the organization's language. Text messages to this customer use the same language. Any other value is rejected with `400`. ## Ownership & permission overrides (optional) These fields control the customer's [managed vs. self-service](/monitoring/managed-vs-self-service) permissions and channel-type policy. They are **organization-write gated**: a customer-scoped caller's writes to these fields are silently ignored server-side. `null` means *inherit from the customer's package config*. | Field | Type | Default | Description | |-------|------|---------|-------------| | `allowSelfService` | boolean\|null | null (inherit) | Whether the customer may create and manage `self_service` monitors | | `maxSelfServiceUrls` | number\|null | null (inherit) | Cap on the customer's **total** `self_service` monitors across all monitor types | | `canEditManaged` | boolean | false | Exception: lets this customer edit `managed` monitors (class flips stay org-only). Changes are written to the audit log. | | `enableEmailAlerts` | boolean\|null | null (inherit) | Whether your organization's own email channels alert about this customer (null = follow the package). Never affects channels the customer sets up themselves | | `enableSmsAlerts` | boolean\|null | null (inherit) | Whether your organization's own SMS channels alert about this customer (null = follow the package). Never affects channels the customer sets up themselves | | `enableWebhookAlerts` | boolean\|null | null (inherit) | Whether your organization's own webhooks channels alert about this customer (null = follow the package). Never affects channels the customer sets up themselves | | `enableIntegrationAlerts` | boolean\|null | null (inherit) | Whether your organization's own integrations channels alert about this customer (null = follow the package). Never affects channels the customer sets up themselves | | `enablePostRequestEscalation` | boolean\|null | null (inherit) | Channel-type policy override: POST-request escalation | The legacy `notificationChannels` JSONB override is deprecated: channel-type policy lives in the `enable*` fields above. ## Example Request ```bash curl -X PATCH "$BASE_URL/api/customers/6bfec6f6-245a-47ce-843b-157d97d56f88" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Customer A GmbH (Updated)", "monthlyReportsEnabled": true }' ``` ## Example Response ```json { "id": 101, "publicId": "6bfec6f6-245a-47ce-843b-157d97d56f88", "organizationId": 1, "name": "Customer A GmbH (Updated)", "email": "contact@customer-a.de", "notificationPhoneNumber": "+491701234567", "notificationEmail": "alerts@customer-a.de", "packageId": 3, "packageType": "growth", "status": "active", "monthlyReportsEnabled": true, "companyName": "Nordwind ApS", "emailLang…
### Get a dependency provider
URL: https://docs.uptimeify.io/api/dependencies/get-dependency
Description: Public, unauthenticated detail of one tracked third-party service: current status, components with 90-day history, and recorded incidents.
Summary: `GET /api/public/dependencies/:slug` No authentication required. `:slug` is the `slug` from [List dependency providers](/api/dependencies/list-dependencies). Contains no customer data. ## Query parameters | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `incidentPage` | integer, 1 to 100000 | `1` | Page of `incidents`, 10 per page | ## Example (cURL) ```bash curl -X GET "https://uptimeify.io/api/public/dependencies/bunny?incidentPage=1" \ -H "Accept: application/json" ``` ## Response ```json { "provider": { "slug": "bunny", "name": "bunny.net", "vendor": "BunnyWay d.o.o.", "homepageUrl": "https://bunny.net", "statusPageUrl": "https://status.bunny.net", "logoUrl": "/img/dependency/bunny.png", "category": "CDN", "status": "operational", "staleness": "fresh", "since": "2026-10-06T09:14:02.000Z", "monitoringSince": "2026-08-20T12:00:00.000Z", "lastCheckedAt": "2026-10-08T15:02:11.000Z", "incidentCount": 14, "statusDerived": false, "noOverallStatus": false }, "components": [ { "id": 812, "name": "CDN", "status": "operational", "statusAsOf": "2026-10-08T15:02:11.000Z", "history": [ { "date": "2026-10-07", "status": "operational", "hasData": true }, { "date": "2026-10-08", "status": "degraded", "hasData": true } ] } ], "incidents": [ { "id": 3051, "title": "Elevated latency in Frankfurt", "titleDe": "Erhöhte Latenz in Frankfurt", "status": "resolved", "impact": "minor", "startedAt": "2026-10-08T07:40:00.000Z", "resolvedAt": "2026-10-08T08:15:00.000Z", "resolutionInferred": false, "scheduledFor": null, "scheduledUntil": null, "affectedComponentCount": 1, "affectedComponentNames": ["CDN"], "shortlink": "https://stspg.io/abc123", "updates": [ { "status": "investigating", "at": "2026-10-08T07:41:00.000Z" }, { "status": "resolved", "at": "2026-10-08T08:15:00.000Z" } ] } ], "incidentsPagination": { "page": 1, "limit": 10, "total": 14, "totalPages": 2 }, "historyIncidents": [ { "startedAt": "2026-10-08T07:40:00.000Z", "resolvedAt": "2026-10-08T08:15:00.000Z", "affectedComponentNames": ["CDN"] } ], "relatedProviders": [ { "slug": "cloudflare", "name": "Cloudflare", "category": "CDN", "logoUrl": "/img/dependency/cloudflare.png", "status": "operational", "sameCategory": true } ], "reportCount": 0, "reportToken": "…" } ``` Notes: - `provider.status`, `staleness`, `statusDerived` and `noOverallStatus` mean the same as in the list endpoint. - `components[].history` covers the last 90 days in UTC, one entry per day; `hasData: false` (with `status: null`) marks a day we have no reading for. `components[].status` is `unknown` with `statusAsOf: null` when our latest reading is older than two hours. - `incidents` is one page of incidents, newest first; `incidentsPagination` says how many pages there are. `historyIncidents` holds up to 50 recent incidents for the 90-day bars and is not paginated. - `resolutionInferred: true` means the provider never posted a resolution and we closed the incident when its components recovered. - `relatedProviders` lists up to 6 other active providers; `sameCategory` marks those in the same category. - `reportCount` is the number of recent user reports, `0` below the publication threshold. `reportToken` belongs to the report form on the web page and is not meant for API use. - Responses for active providers carry `Cache-Control: public, max-age=30`. ## Common errors - `404 Provider not found` (`data.code: providerNotFound`) when the slug does not exist or the provider is not active - `400` (`data.code: invalidIncidentPage`) when `incidentPage` is not an integer from 1 to 100000 - `500 Unexpected server error` on an internal failure
### List dependency providers
URL: https://docs.uptimeify.io/api/dependencies/list-dependencies
Description: Public, unauthenticated list of the third-party services whose status Uptimeify tracks, with each one's current overall status.
Summary: `GET /api/public/dependencies` No authentication required. Returns every active provider on the [Dependency Monitoring](https://uptimeify.io/dependency) page, ordered by name. Contains no customer data, only what we observe on each provider's own public status page. ## Query Parameters | Parameter | Type | Default | Description | |---|---|---|---| | `envelope` | string | none | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ## Example (cURL) ```bash curl -X GET "https://uptimeify.io/api/public/dependencies?envelope=items" \ -H "Accept: application/json" ``` ## Response ```json { "items": [ { "slug": "bunny", "name": "bunny.net", "vendor": "BunnyWay d.o.o.", "category": "CDN", "logoUrl": "/img/dependency/bunny.png", "status": "operational", "staleness": "fresh", "since": "2026-10-06T09:14:02.000Z", "statusDerived": false, "noOverallStatus": false } ], "total": 1, "page": 1, "perPage": 1 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form (a bare array of the same items), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. Notes: - `status` is one of `operational`, `maintenance`, `degraded`, `partial_outage`, `major_outage`, `unknown`. A provider we have never checked, or can no longer read, is listed as `unknown` rather than left out. - `staleness` is `fresh`, `stale` or `unknown`: whether the current `status` rests on a recent successful read of the provider's status page. - `since` is when the current `status` began (ISO 8601), `null` if not known yet. - `statusDerived` is `true` when the provider publishes no overall status and we derive it from its components; `noOverallStatus` is `true` when neither is possible and only components are shown. - `logoUrl` is a path on `uptimeify.io` or our CDN, or `null`. - An empty array is a valid answer: the list only contains active providers. ## Common errors - `500 Unexpected server error` on an internal failure
### Error codes and known API pitfalls
URL: https://docs.uptimeify.io/api/error-codes-and-known-pitfalls
Description: This page documents real integration issues that have occurred in production or testing.
Summary: ## Schema | Error Code | Cause | Solution / Bug | | --- | --- | --- | | `404 Website not found` | Some website sub-endpoints previously accepted only the legacy numeric website ID, even though the docs showed `websitePublicId`. | Fixed. `GET /api/websites/:websitePublicId/check-history` and `GET /api/websites/:websitePublicId/uptime-stats` now accept public IDs and still keep legacy-ID compatibility. | | `403 Forbidden` on `GET /api/organizations/:organizationPublicId` | The route previously interpreted the path parameter directly as a number. A UUID therefore failed during permission checks. | Fixed. Organization detail and billing routes now resolve `publicId` correctly. | | `400 Bad Request` with `ZodError` on `customer-ips` or `customer-domains` | Query parameters like `organizationId=`, `page=`, or `perPage=` were sent as empty strings. Zod coerced them to `0`, which then violated min constraints. | Fixed for `organizationId`, `page`, and `perPage`. Optional still means: omit unused parameters instead of sending empty strings. | ## Monitor ownership error codes Since the [managed vs. self-service](/monitoring/managed-vs-self-service) model, monitor write endpoints of **all** types (website, DNS, ICMP, SMTP, SSH, FTP, IMAP/POP, domain, DNSBL) can return these `403` codes in `data.code`: | Code | Meaning | | --- | --- | | `managed_by_organization` | A customer-scoped caller tried to edit/delete a `managed` monitor without the `canEditManaged` exception. Open a [change request](/api/change-requests) instead. Also for a `managed` status page and what hangs off it (settings, components, groups, domain, subscribers, incidents and maintenance on the page), for customer-bound users with any role (also `readonly` and `editor`) and customer-bound tokens; ask with [Create Status Page Change Request](/api/change-requests/create-status-page-change-request) instead. | | `selfServiceNotAllowed` | A customer-scoped caller tried to create a monitor but the customer's resolved `allowSelfService` is false. | | `selfServiceQuotaReached` | Creating (or flipping to) a `self_service` monitor would exceed the customer's `maxSelfServiceUrls`: the quota counts **all** monitor types together. | | `managementTypeOrgOnly` | A non-org-admin tried to change a monitor's `managementType`. Class flips are organization-admin-only, and since 04.09.2026 that is enforced against customer-scoped API tokens too: such a token is synthesized with an admin role but restricted scope, and the flip now requires unrestricted scope. | | `readonlyMayNotDelete` | A caller with the `readonly` role tried to delete a monitor. Deleting is closed to that role on every ownership class, `self_service` included, and an API token issued by a read-only user inherits the restriction. Editing a `self_service` monitor stays permitted. | | `tooManyOpenRequests` | (`429`) The customer already has 10 open change requests. | ## Monitor quota error codes An organization has a monitor quota. Creating a monitor while that quota is exhausted either fails, or, when the organization has automatic quota upgrading switched on, moves it to the next quota tier - and that tier has a higher monthly price, with the difference billed for the rest of the current period. | Code | Meaning | | --- | --- | | `monitorQuotaReached` | (`403`) The organization is at its monitor quota and does NOT upgrade automatically. Free up a monitor or raise the quota. | | `monitorQuotaNoHigherTier` | (`403`) The organization is at its quota, upgrades automatically, and is already on the highest predefined tier. Contact support. | | `paidQuotaUpgradeNotAuthorized` | (`403`) The call would have triggered a PAID upgrade and did not authorize one. This can only happen on an agent (MCP) connection: a person in the dashboard sees the tier and its price, a model does not, so a billing effect starts opted out. The message names the tier and the monthly price the call would have bought. Send `allowPaidQuotaUpgrade: true` once a pe…
### Escalation Config
URL: https://docs.uptimeify.io/api/escalation
Description: Manage organization-level webhook escalation settings and default notification channels.
Summary: The escalation config auto-creates with sensible defaults when first accessed. ## Authentication All endpoints accept either session cookies or API bearer tokens: ```bash BASE_URL="https://uptimeify.io" TOKEN="" ``` ## Default Webhook Body Template Variables | Variable | Description | |----------|-------------| | `{{websiteName}}` | Name of the affected website | | `{{websiteUrl}}` | URL of the affected website | | `{{status}}` | Current status (e.g. `down`, `up`) | | `{{startedAt}}` | Incident start timestamp | | `{{incident}}` | Incident details object | | `{{errorMessage}}` | Error message if available | ## Endpoints - [Get Escalation Config](/api/escalation/get-escalation-config) - [Update Escalation Config](/api/escalation/update-escalation-config) - [Test Escalation Config](/api/escalation/test-escalation-config)
### Get Escalation Config
URL: https://docs.uptimeify.io/api/escalation/get-escalation-config
Description: Returns the escalation config for an organization. The :id parameter is the organization ID. If no config is saved yet, the inactive defaults are returned (`id`, `createdAt` and `updatedAt` are `null`) and nothing is created; the first PATCH stores them.
Summary: `GET /api/escalation-config/:id` Also returns the organization's default notification settings and all notification channels. Header values are never returned: `webhookHeaders` keeps the header names with `null` values, and `hasWebhookHeaders` says whether any header is stored. The same holds for `config.headers` of the channels in `notificationChannels` (names with `null`, plus `hasHeaders`). Header values are stored encrypted. ## Example (cURL) ```bash curl -X GET "$BASE_URL/api/escalation-config/1" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "id": 1, "organizationId": 1, "webhookUrl": "https://deinkunde.com/webhook", "webhookMethod": "POST", "webhookHeaders": { "Content-Type": null }, "hasWebhookHeaders": true, "webhookBodyTemplate": "{\"websiteName\":\"{{websiteName}}\",...}", "webhookTimeout": 30, "webhookRetryAttempts": 3, "webhookRetryDelay": 60, "expectedStatusCodes": "200,201,202,204", "isActive": false, "lastTestedAt": null, "lastTestStatus": null, "lastTestError": null, "organization": { "defaultEmail": "ops@deinkunde.com", "defaultPhoneNumber": "+1234567890", "defaultNotificationChannels": null, "defaultNotificationTargets": null, "defaultNotificationRules": null }, "notificationChannels": [] } ``` ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` unless you are an organization admin with unrestricted scope (`forbidden`, or `customerScopedTokenForbidden` for a customer-bound token or login). The response contains the webhook URL, headers and body template, so read access is not enough.
### Test Escalation Config
URL: https://docs.uptimeify.io/api/escalation/test-escalation-config
Description: Tests the escalation config by sending a test webhook, PagerDuty event, or Pushover notification. All body fields are optional and override DB values for testing.
Summary: `POST /api/escalation-config/:id/test` ## Request Body (all optional) | Field | Type | Description | |-------|------|-------------| | `type` | string | `pagerduty` or `pushover` for dedicated handlers | | `config` | object | PagerDuty config `{routingKey}` or Pushover config `{userKey, apiToken}` | | `webhookUrl` | string | Override webhook URL for test | | `webhookMethod` | string | Override webhook method | | `webhookHeaders` | object | Override webhook headers. Same block list as on PATCH: `Host` answers `400` `webhookHostHeaderForbidden`; `Authorization`, `Cookie`, `X-Forwarded-*` and `Proxy-*` answer `400` `invalidRequestBody`. | | `webhookBodyTemplate` | string | Override webhook body template | | `webhookTimeout` | number | Override webhook timeout | | `expectedStatusCodes` | string | Override expected status codes | ## Example (cURL): Webhook test ```bash curl -X POST "$BASE_URL/api/escalation-config/1/test" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "webhookUrl": "https://httpbin.org/post", "webhookMethod": "POST", "webhookTimeout": 15 }' ``` ## Example (cURL): PagerDuty test ```bash curl -X POST "$BASE_URL/api/escalation-config/1/test" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "pagerduty", "config": { "routingKey": "your-routing-key-here" } }' ``` ## Response (webhook) ```json { "success": true, "statusCode": 200, "message": "Webhook delivered successfully" } ``` ## Response (PagerDuty) ```json { "success": true, "message": "PagerDuty event enqueued successfully" } ``` ## Common errors - `401 Unauthorized` when not authenticated - `400` (`organizationIdRequired`) when the organization id is missing or not a positive integer. Checked after authentication since 20.10.2026; before, it answered `400` even without a session. - `403 Forbidden` (`forbidden`) unless you are an organization admin, or (`customerScopedTokenForbidden`) when your scope is restricted to customers. The second case is new since 20.10.2026, matching `GET` and `PATCH`.
### Update Escalation Config
URL: https://docs.uptimeify.io/api/escalation/update-escalation-config
Description: Updates the escalation config. The :id parameter is the organization ID. If no config exists, one is upserted.
Summary: `PATCH /api/escalation-config/:id` ## Request Body (all optional) | Field | Type | Description | |-------|------|-------------| | `webhookUrl` | string\|null | Webhook URL. Set to `null` to deactivate the webhook channel. | | `webhookMethod` | string | HTTP method: `POST`, `PUT`, or `PATCH` | | `webhookHeaders` | object\|string | JSON headers object. Replaces the stored headers; a header whose value is `null` or `""` keeps its stored value. The response returns names only, like GET. | | `webhookBodyTemplate` | string | JSON body template with `{{variables}}` | | `webhookTimeout` | integer | Timeout in seconds | | `webhookRetryAttempts` | integer | Number of retries | | `webhookRetryDelay` | integer | Seconds between retries | | `expectedStatusCodes` | string | Comma-separated expected status codes | | `isActive` | boolean | Enable or disable the webhook. `false` deactivates only the organization webhook channel (no `websiteId`, no customer); customer webhook channels stay active. | | `defaultEmail` | string | **Side-effect:** creates/updates an org-level email notification channel | | `defaultPhoneNumber` | string | **Side-effect:** creates/updates an org-level SMS notification channel | ## Example (cURL) ```bash curl -X PATCH "$BASE_URL/api/escalation-config/1" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "webhookUrl": "https://deinkunde.com/webhook", "webhookMethod": "POST", "webhookHeaders": { "Content-Type": "application/json" }, "webhookTimeout": 30, "webhookRetryAttempts": 3, "isActive": true, "defaultEmail": "alerts@deinkunde.com" }' ``` ## Common errors - `400 Bad Request` with `data.code` `smsCountryNotAllowed` when `defaultPhoneNumber` is not in international format (`+` and country calling code) or not from the EU/EEA, Switzerland or the UK - `401 Unauthorized` when not authenticated - `403 Forbidden` with insufficient permissions ## Response Returns the updated escalation config object. See [Error Codes](/api/error-codes-and-known-pitfalls) for error responses.
### Examples
URL: https://docs.uptimeify.io/api/examples
Description: Here you’ll find step-by-step examples for common API workflows.
Summary: - [Create a customer + website](/api/examples/create-customer-and-website) - [Delete a customer including all websites](/api/examples/delete-customer-and-all-websites) - [Create a customer + all monitor types](/api/examples/create-customer-and-all-monitors) - [Create a customer + multiple monitors](/api/examples/create-customer-and-multiple-monitors)
### Create a customer + all monitor types
URL: https://docs.uptimeify.io/api/examples/create-customer-and-all-monitors
Description: This example is useful if you want to bootstrap a customer with a complete monitoring baseline.
Summary: High-level flow: 1. Create customer 2. Create website 3. Create monitors (one per monitor type) ## 1) Create customer + website Reuse: - [Create a customer + website](/api/examples/create-customer-and-website) ## 2) Create monitors (one per type) Monitor APIs are organized by type. API reference overview: - [Monitors API](/api/monitors) Typical types you might create: - DNS Monitor - ICMP Monitor - SMTP Monitor - SSH Monitor - TCP Port Monitor - FTP Monitor - IMAP/POP Monitor For details and required fields, follow the per-type API docs. ### Example: create a DNS monitor ```bash curl -X POST "$API_BASE_URL/api/dns-monitors" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customerId": 123, "name": "DNS: deinkunde.com", "hostname": "deinkunde.com", "dnsConfig": { "rrtypes": ["A", "AAAA"], "matchMode": "exact", "expectedValues": { "A": ["93.184.216.34"], "AAAA": ["2606:2800:220:1:248:1893:25c8:1946"] } } }' ``` ### Example: create an ICMP monitor ```bash curl -X POST "$API_BASE_URL/api/icmp-monitors" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customerId": 123, "name": "Ping: gateway", "hostname": "gateway.deinkunde.com" }' ``` ### Example: create a TCP Port monitor ```bash curl -X POST "$API_BASE_URL/api/tcp-monitors" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customerId": 123, "name": "Redis Primary", "hostname": "redis.deinkunde.com", "port": 6379, "config": { "expectBanner": "+PONG" } }' ``` ## Notes - Not every installation exposes every monitor type, and required fields can vary (plan/package). - For website (HTTP) checks, start with the website’s own monitoring settings: [Website Configuration API](/api/website-configuration)
### Create a customer + multiple monitors
URL: https://docs.uptimeify.io/api/examples/create-customer-and-multiple-monitors
Description: This example shows how to set up multiple monitors for a single customer, e.g.:
Summary: - Two different hostnames for DNS monitoring - Multiple servers for ICMP - A mix of DNS + ICMP + SMTP ## 1) Create customer + website - [Create a customer + website](/api/examples/create-customer-and-website) ## 2) Create multiple monitors ### Option A: Multiple monitors of the same type (DNS) ```bash # DNS monitor 1 curl -X POST "$API_BASE_URL/api/dns-monitors" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customerId": 123, "name": "DNS: app.deinkunde.com", "hostname": "app.deinkunde.com", "dnsConfig": { "rrtypes": ["A"], "matchMode": "exact", "expectedValues": { "A": ["93.184.216.34"] } } }' # DNS monitor 2 curl -X POST "$API_BASE_URL/api/dns-monitors" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customerId": 123, "name": "DNS: mail.deinkunde.com", "hostname": "mail.deinkunde.com", "dnsConfig": { "rrtypes": ["MX", "TXT"], "matchMode": "contains", "expectedValues": { "MX": ["10 mail.deinkunde.com"], "TXT": ["v=spf1 include:_spf.deinkunde.com ~all"] } } }' ``` ### Option B: Mix different monitor types ```bash # ICMP curl -X POST "$API_BASE_URL/api/icmp-monitors" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customerId": 123, "name": "Ping: edge-1", "hostname": "edge-1.deinkunde.com" }' # SMTP curl -X POST "$API_BASE_URL/api/smtp-monitors" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customerId": 123, "name": "SMTP: outbound", "hostname": "smtp.deinkunde.com", "port": 587 }' ``` ## Tips - Use consistent naming conventions (prefix by type: `DNS:`, `Ping:`, `SMTP:`). - Start with conservative intervals and tighten later. ## Reference - [Monitoring Types](/monitoring/monitoring-types/uptime) - [Monitors API](/api/monitors)
### Create a customer + website
URL: https://docs.uptimeify.io/api/examples/create-customer-and-website
Description: This example shows a typical onboarding flow:
Summary: 1. Create a **customer** 2. Create a **website** for that customer 3. (Optional) Attach monitoring configuration > If you prefer the UI: you can create customers and websites in the Admin area. The API is useful for automation and bulk setups. ## Prerequisites - An API token with the required scopes - Your API base URL (e.g. `https://your-instance.tld`) See the API introduction first: - [API Introduction](/api/introduction) ## 1) Create customer API reference: - [Customers API](/api/customers) Example (pseudo request): ```bash curl -X POST "$API_BASE_URL/api/customers" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme GmbH", "email": "ops@deinkunde.com" }' ``` Store the returned `customerId`. ## 2) Create website for the customer API reference: - [Websites API](/api/websites) ```bash curl -X POST "$API_BASE_URL/api/websites" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customerId": 123, "name": "Acme Marketing Website", "url": "https://deinkunde.com" }' ``` Important: - `url` must include the protocol (`https://...`). ## 3) Verify the website API reference: - [Get website](/api/websites/get-website) ```bash curl -X GET "$API_BASE_URL/api/websites/456" \ -H "Authorization: Bearer $TOKEN" ``` ## Next steps - Configure monitoring behavior per website: [Website Configuration API](/api/website-configuration) - Learn which monitor types exist: [Monitoring Types](/monitoring/monitoring-types/uptime)
### Delete a customer including all websites
URL: https://docs.uptimeify.io/api/examples/delete-customer-and-all-websites
Description: This example focuses on a safe, explicit deletion flow.
Summary: Depending on your configuration, deleting a customer may or may not automatically delete related websites. To avoid surprises, we recommend deleting websites explicitly first. ## Prerequisites - An API token with the required scopes ## 1) List websites for the customer API reference: - [List websites](/api/websites/list-websites) Pseudo request: ```bash curl -X GET "$API_BASE_URL/api/websites?customerId=123" \ -H "Authorization: Bearer $TOKEN" ``` Collect all website IDs. ## 2) Delete each website API reference: - [Delete website](/api/websites/delete-website) ```bash curl -X DELETE "$API_BASE_URL/api/websites/456" \ -H "Authorization: Bearer $TOKEN" ``` Repeat for all websites of that customer. ## 3) Delete the customer API reference: - [Customers API](/api/customers) ```bash curl -X DELETE "$API_BASE_URL/api/customers/123" \ -H "Authorization: Bearer $TOKEN" ``` ## Notes - If your backend supports cascade deletes, step 2 might be optional, but doing it explicitly keeps automation predictable.
### Incident Management
URL: https://docs.uptimeify.io/api/incident-management
Description: Public REST API for Uptimeify Incident Management (IM): ingest alerts from your own monitoring systems and manage incidents programmatically.
Summary: Incident Management (IM) is a separate domain from Monitoring: a two-level alert/incident model with teams, on-call schedules, and escalation tiers. This section covers the public REST endpoints for ingesting alerts and managing incidents. ## Authentication Almost every endpoint below accepts an **organization-wide** API token. Three exceptions: [My On-Call Status](/api/incident-management/my-on-call), the [personal notification settings](/api/incident-management/notification-settings) and the setup [test page](/api/incident-management/setup) describe a person and need a user session; the [Ingest Webhook](/api/incident-management/ingest-webhook) authenticates with the token in its URL instead. With an API token: ```bash BASE_URL="https://uptimeify.io" TOKEN="wsm_" ``` Create one via [Create Organization Token](/api/api-tokens/create-organization-token) and leave `customerId` unset. A token created **with** a `customerId` (a customer-scoped token) is rejected on every IM path with `403 Forbidden` (`customerScopedTokenForbidden`); Incident Management has no customer-facing surface, by design. Incident Management must also be **activated** for your organization, or every endpoint below returns `403 Forbidden` (`imNotEnabled`). An organization-wide token acts with the **current role of the person who created it**, read on every request. Organization tokens can only be created by organization admins, so a token normally acts as `admin` and passes every team check in this section (for example "member of the incident's team"). If its creator is later demoted to `editor` or `responder`, the token keeps that role's access and loses the admin-only write rights. If the creator becomes `readonly`, is deactivated or deleted, the token loses Incident Management entirely (`403` `imAccessDenied`). A token is not a person. Changes made with it are recorded without one: `createdBy`, `acknowledgedBy` and `resolvedBy` on the incident and `actorUserId` on its timeline events stay `null`, like for a system event. ## Endpoints ### Getting started - [Activate Incident Management](/api/incident-management/activate): `POST /api/im/activate` - [Setup Progress and Test Page](/api/incident-management/setup): `GET/PATCH /api/im/setup/state`, `POST /api/im/setup/test-page` ### Alerts and on-call - [Events Ingest](/api/incident-management/events-ingest): `POST /api/im/events` - [Ingest Webhook](/api/incident-management/ingest-webhook): `POST /api/im/ingest/:token` - [Who Is On Call](/api/incident-management/on-call): `GET /api/im/on-call` - [My On-Call Status](/api/incident-management/my-on-call): `GET /api/im/me/on-call`, `GET /api/im/me/on-call-stats` - [Personal Notification Settings](/api/incident-management/notification-settings): `/api/im/notification-settings/**` - [User Notification Settings](/api/incident-management/user-notification-settings): `/api/im/users/:userId/notification-settings` (admin) - [Default Notifications](/api/incident-management/notification-template): `/api/im/notification-template` (admin) ### Incidents - [List Incidents](/api/incident-management/list-incidents): `GET /api/im/incidents` - [Count Open Incidents](/api/incident-management/incident-count): `GET /api/im/incidents/count` - [Get Incident](/api/incident-management/get-incident): `GET /api/im/incidents/:id` - [Find the Incident for a Monitoring Incident](/api/incident-management/incident-by-monitor): `GET /api/im/incidents/by-monitor/:id` - [Create Incident](/api/incident-management/create-incident): `POST /api/im/incidents` - [Acknowledge / Update Incident Status](/api/incident-management/acknowledge-incident): `POST /api/im/incidents/:id/ack` and `POST /api/im/incidents/:id/status` - [Resolve Incident](/api/incident-management/resolve-incident): `POST /api/im/incidents/:id/resolve` - [Change Incident Severity](/api/incident-management/incident-severity): `POST /api/im/incidents/:id/severity` - [Snooze Incident](/api/incident-management…
### Acknowledge / Update Incident Status
URL: https://docs.uptimeify.io/api/incident-management/acknowledge-incident
Description: Acknowledges an Incident Management incident, or moves it between the open statuses (acknowledged, investigating, identified, monitoring).
Summary: Two endpoints change an open incident's status: - [Acknowledge](#acknowledge) is the idempotent "I have got this" call. It acts on any open incident that has not been acknowledged yet and is open to everyone with IM access, because an acknowledgement only ever stops paging. - [Change status](#change-status) moves an incident between the open statuses, including `acknowledged`. It is restricted to the incident's team. Neither endpoint can reach `resolved` (use [Resolve Incident](/api/incident-management/resolve-incident)) or `merged` (use [Merge Incidents](/api/incident-management/merge-incidents)). **What an acknowledgement stops** depends on the incident's current escalation tier. By default it stops the whole escalation chain. If that tier is configured to stop escalating only on resolve, an acknowledgement silences the current page but further tiers keep escalating until the incident is resolved. ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token, see [Authentication](/api/incident-management#authentication). Incident Management must be enabled for the organization. ## Acknowledge `POST /api/im/incidents/:id/ack` Acknowledges an open incident that has no acknowledgement yet (`acknowledgedAt` is `null`). A `triggered` incident moves to `acknowledged`. An incident that was moved to `investigating`, `identified` or `monitoring` without an acknowledgement keeps its status, but the acknowledgement is recorded (`acknowledgedBy`, `acknowledgedAt`) and escalation stops exactly as for a `triggered` one; `status` in the response is that unchanged status. Calling it again, or calling it on a `resolved` or `merged` incident, is not an error: the response says `alreadyAcknowledged: true` and reports the current status. The timeline records the acknowledgement with `source: "api"` for an API token and `source: "ui"` for a browser session. No request body. ### Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/incidents/42/ack" \ -H "Authorization: Bearer $TOKEN" ``` ### Response `200 OK`, first acknowledgement: ```json { "acknowledged": true, "alreadyAcknowledged": false, "status": "acknowledged", "acknowledgedBy": "MFcTjWmYq2LpzR8vK1sXo", "acknowledgedAt": "2026-07-17T09:20:00.000Z" } ``` Both responses carry `acknowledgedAt` (ISO timestamp, or `null` for a `resolved`/`merged` incident that was never acknowledged). The incident counts as acknowledged when `acknowledgedAt` is set or `status` is `resolved` or `merged`; do not infer it from `acknowledgedBy`, which is `null` when an API token acknowledged. `200 OK`, incident was already acknowledged: ```json { "acknowledged": true, "alreadyAcknowledged": true, "status": "investigating", "acknowledgedBy": "MFcTjWmYq2LpzR8vK1sXo", "acknowledgedAt": "2026-07-17T09:20:00.000Z" } ``` ### Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the session user has no IM-eligible role - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization - `400 Bad Request` (`invalidRequestBody`) when `:id` is not a positive integer - `404 Not Found` (`imIncidentNotFound`) when the incident does not exist, or belongs to another organization ## Change status `POST /api/im/incidents/:id/status` Moves an incident between the open statuses `triggered`, `acknowledged`, `investigating`, `identified` and `monitoring`. Any of the four non-`triggered` statuses is a valid target from any open status, not just the "next" one; `triggered` itself is never a target. Setting `acknowledged` acknowledges the incident and stops escalation as described above. Moving straight from `triggered` to `investigating`, `identified` or `monitoring` does **not** record an acknowledgement. Restricted to the incident's team: you must be a member of the incident's team (`teamId`) or an organization admin. An organizatio…
### Activate Incident Management
URL: https://docs.uptimeify.io/api/incident-management/activate
Description: Switches Incident Management on for your organization. Idempotent: calling it again on an enabled organization changes nothing.
Summary: `POST /api/im/activate` Turns Incident Management on for your organization. Until this has run, every other endpoint of this API answers `403` with `imNotEnabled`; this one (and the [setup state](/api/incident-management/setup)) is reachable before activation on purpose. Activation is idempotent. On an organization that is already enabled it returns `alreadyEnabled: true` and changes nothing. On the first activation Uptimeify also runs its activation hooks, for example the backfill that brings open monitoring incidents into Incident Management when the monitoring bridge is on. A hook that fails does not undo the activation; its name is listed in `hookErrors`. ## Authentication Requires an IM-eligible role and **write access to the organization**: the `admin` role of that organization, or an organization-wide API token created by an organization admin. `editor` and `responder` receive `403` (`forbidden`). ## Query parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `organizationId` | number | No | The organization to activate. Defaults to your own organization. Naming another organization only succeeds for platform administrators. | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/activate" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response First activation: ```json { "organizationId": 42, "enabled": true, "monitoringBridge": true, "alreadyEnabled": false, "hookErrors": [] } ``` Already enabled: ```json { "organizationId": 42, "enabled": true, "monitoringBridge": true, "alreadyEnabled": true } ``` | Field | Description | |-------|-------------| | `monitoringBridge` | Whether incidents from Uptimeify's own monitoring are bridged into Incident Management. Change it in the [organization settings](/api/incident-management/org-settings). | | `hookErrors` | Names of activation hooks that failed. Empty on success. Only present on the first activation. | ## Common errors - `400 Bad Request` (`organizationIdRequired`) when no organization can be determined - `401 Unauthorized` when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the caller has no IM-eligible role - `403 Forbidden` (`forbidden`) when the caller is not an admin of the organization
### Alert Source Setup Guides
URL: https://docs.uptimeify.io/api/incident-management/alert-sources
Description: Step-by-step guides for wiring Zabbix, Datadog, Grafana Alerting, Prometheus Alertmanager, Sentry, Beszel, or any custom webhook to Uptimeify Incident Management.
Summary: Each guide below walks through configuring one monitoring/alerting tool to send its alerts to an Uptimeify **alert source**: a per-tool ingest endpoint with a built-in field mapping, so alerts land in Incident Management already normalized (title, severity, status, host) without writing a custom integration. ## Guides - [Zabbix](/api/incident-management/alert-sources/zabbix) - [Datadog](/api/incident-management/alert-sources/datadog) - [Grafana Alerting](/api/incident-management/alert-sources/grafana-alerting) - [Prometheus Alertmanager](/api/incident-management/alert-sources/prometheus-alertmanager) - [Sentry](/api/incident-management/alert-sources/sentry) - [Beszel](/api/incident-management/alert-sources/beszel) - [Custom webhook](/api/incident-management/alert-sources/custom-webhook) - [Email](/api/incident-management/alert-sources/email) - [Report form](/api/incident-management/alert-sources/report-form) The **Email** guide works differently from the rest: an email source has no JSON webhook payload, so the "How ingestion works" and "Severity mapping" sections below (both webhook-specific) don't apply to it; see that guide directly. ## How ingestion works 1. In the Uptimeify dashboard, go to **Incident Management → Alert Sources → New** and pick the preset matching your tool. Give it a name and assign it to a team. 2. Uptimeify generates a unique ingest URL: ``` https:///api/im/ingest/ ``` The `` is shown **once**, immediately after the source is created. Copy it right away. It is never shown again in cleartext. If you lose it, open the source's **Settings** tab and rotate the token to get a fresh URL (also shown only once). 3. Configure your tool (see the tool-specific guide) to send an HTTP `POST` request with a JSON body to that URL whenever it fires or resolves an alert. 4. Uptimeify parses the payload using the preset's field mapping (or your own edited mapping, from the source's **Payload Mapping** tab) and queues it for asynchronous processing into Incident Management. This is a different mechanism from the [Events Ingest](/api/incident-management/events-ingest) endpoint (`POST /api/im/events`): that endpoint is authenticated with an organization-wide API token and has no preset field mapping (every request maps through a single auto-provisioned `api`-type source). The per-tool ingest URL above needs no API token (the token embedded in the URL **is** the credential, so treat the full URL like a password), but comes with a ready-made mapping for the tool you picked. If your tool can sign requests or send a header, you can additionally require an HMAC signature (`X-Uptimeify-Signature` + `X-Uptimeify-Timestamp`) or an `Authorization: Bearer` token per source. Sources can also be created, rotated and tested programmatically. Both are described in the [Alert Sources API](/api/incident-management/alert-sources-api). ## Request limits The same limits apply to every ingest URL, regardless of preset: | Limit | Value | Failure | |-------|-------|---------| | Body size | 256 KB | `413 Payload Too Large` (`payload_too_large`) | | JSON nesting depth | 20 levels | `422 Unprocessable Entity` (`payload_too_deep`) | | Valid JSON | required | `422 Unprocessable Entity` (`invalid_json`) | | Requests per alert source | 300 per minute | `429 Too Many Requests` (`imIngestRateLimited`, `data.retryAfter`) | | Ingest bytes per organization | 50 MiB per hour | `429 Too Many Requests` (`imIngestByteBudgetExceeded`, `data.retryAfter`) | An empty request body is treated as `{}`. ## Response A successful request returns `202 Accepted` within a few seconds: the alert is stored durably, not yet processed. If our queue is briefly unavailable, it is held in a fallback store and processed as soon as the queue is back: ```json { "accepted": true } ``` An unknown, wrong, or rotated-away token returns `404 Not Found` (`not_found`). Every kind of authentication failure returns this same response, by design. It never reveals wh…
### Alert Sources API
URL: https://docs.uptimeify.io/api/incident-management/alert-sources-api
Description: Create, configure and test Incident Management alert sources: ingest tokens, optional HMAC or Bearer authentication, payload mapping, maintenance windows and per-source statistics.
Summary: An **alert source** is an inbound integration. Each webhook source has its own ingest URL (`https://uptimeify.io/api/im/ingest/`) and a payload mapping that turns the vendor's JSON into an alert. The [setup guides](/api/incident-management/alert-sources) explain how to point Zabbix, Datadog, Grafana and others at that URL. This page covers the endpoints that manage the sources themselves. ## Authentication Every endpoint needs IM access: an IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token. Incident Management must be enabled for the organization. A customer-scoped token is rejected with `403 Forbidden` (`customerScopedTokenForbidden`). - **Read endpoints** (list, detail, presets, payloads, stats, test-mapping) are open to every IM-eligible caller. - **Write endpoints** (create, update, delete, token and secret rotation, disable-auth, test-alert) additionally require the role `admin` or a team-admin membership in the source's team. An API token carries the role of the user who created it, so use a token created by an organization admin. Sources are scoped to your organization. A source of another organization answers `404 Not Found` (`imSourceNotFound`), never `403`. ## The source object List, detail, update and disable-auth return this shape. Credentials never appear in it: the ingest token, the bearer token and the HMAC secret are only returned once, by the endpoint that mints them. | Field | Type | Description | |-------|------|-------------| | `id` | number | Source ID. | | `organizationId` | number | Owning organization. | | `teamId` | number | Team whose escalation the source feeds. | | `name` | string | Display name, up to 120 characters. | | `type` | string | `zabbix`, `datadog`, `grafana`, `alertmanager`, `sentry`, `beszel`, `custom`, `api`, `email`, `form` (the public [report form](/api/incident-management/alert-sources/report-form)), or `uptimeify_monitoring` (the built-in bridge from classic monitoring, created by the platform). | | `authMode` | object | `{ urlToken?, hmac?: { enabled }, bearer?: { enabled } }`. See [Optional request authentication](#optional-request-authentication). | | `payloadMapping` | object | Field mapping applied to every inbound payload. | | `autoResolve` | boolean | Whether a resolve event closes the incident automatically. Copied onto each new incident. | | `groupingWindowMinutes` | number or null | Grouping window. `null` groups by dedup key only. | | `maintenance` | object or null | Recurring maintenance windows, `{ windows: [...] }`. | | `snoozeUntil` | ISO 8601 or null | Ad hoc mute until this instant. | | `secondaryExpiresAt` | ISO 8601 or null | Until when the previous ingest token still works after a rotation. | | `createdAt`, `updatedAt` | ISO 8601 | Timestamps. | ```json { "id": 7, "organizationId": 1, "teamId": 3, "name": "Zabbix production", "type": "zabbix", "secondaryExpiresAt": null, "payloadMapping": { "title": "trigger_name", "severity": "event_severity", "status": "trigger_status", "host": "host_name", "dedupKey": "event_id", "severityMap": { "Disaster": "sev1", "High": "sev2", "Average": "sev3", "Warning": "sev4", "Information": "sev4", "Not classified": "sev4" }, "resolveValues": ["RESOLVED", "OK"] }, "autoResolve": true, "groupingWindowMinutes": null, "maintenance": null, "snoozeUntil": null, "createdAt": "2026-10-01T08:00:00.000Z", "updatedAt": "2026-10-01T08:00:00.000Z", "authMode": {} } ``` **Deprecated fields:** until 2027-01-18 responses still carry `authMode.url_token` next to `authMode.urlToken` and request bodies still accept it; a failed [mapping test](#test-a-mapping) still carries `error` next to `errorMessage`. Use the successors; `url_token` and `urlToken` with different values answer `400` `invalidRequestBody`. ## List sources `GET /api/im/sources` Returns all sources of your organization, sorted by name. | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `envelope` | string…
### Beszel
URL: https://docs.uptimeify.io/api/incident-management/alert-sources/beszel
Description: Send Beszel server alerts to Uptimeify Incident Management through a Shoutrrr generic webhook, with host, link, severity and automatic recovery for every Beszel alert type.
Summary: [Beszel](https://beszel.dev) notifies through [Shoutrrr](https://beszel.dev/guide/notifications/) URLs. Its generic webhook sends only a title and a message, with no status field and no alert id. The Beszel preset reads everything it needs from the title: whether the alert fires or recovers, which system it is about, and which earlier alert a recovery closes. Checked against the alert texts of Beszel 0.21. ## 1. Create the alert source in Uptimeify Go to **Incident Management → Alert Sources → New**, pick the **Beszel** preset, name it, and create it. The success screen shows a ready-made **notification URL for Beszel**: ``` generic:///api/im/ingest/?template=json ``` It is shown once and never displayed again in cleartext. If you lose it, rotate the token from the source's **Settings** tab and build the URL again from the new ingest URL: replace `https://` with `generic://` and append `?template=json`. `template=json` is required. Without it Beszel sends plain text instead of `{ "title", "message" }`, and the preset has nothing to read. ## 2. Add the URL in Beszel 1. In Beszel, open **Settings → Notifications**. 2. Under **Webhook / Push notifications**, add the URL from step 1 and save. **Test URL** sends a test notification. It arrives as an open alert titled `Test Alert`; resolve it by hand. 3. In the systems table, open the bell icon of each system and enable the alerts you want (status, CPU, memory, disk, and so on). Beszel sends one notification when an alert fires and one when it recovers. Both reach the same Uptimeify alert, so the recovery resolves it. ## Supported alert types | Beszel alert | Firing title | Recovery title | |---|---|---| | CPU, memory, disk, bandwidth, temperature, load, GPU | `web-01 CPU above threshold` | `web-01 CPU below threshold` | | Battery (fires when low) | `web-01 battery below threshold` | `web-01 battery above threshold` | | Status (connection) | `Connection to web-01 is down 🔴` | `Connection to web-01 is up ✅` | | Container health | `Unhealthy container db on web-01 🔴` or `3 unhealthy containers on web-01 🔴` | `web-01 containers are healthy ✅` | | systemd services | `Failed services on web-01 🔴` | `Services recovered on web-01 ✅` | | Network monitor (packet loss) | `Network monitor loss on web-01: 1.1.1.1:53` | `Network monitor recovered on web-01: 1.1.1.1:53` | | SMART | `SMART failure on web-01: /dev/sda 🔴` | none | | ZFS pool | `Storage pool DEGRADED on web-01: tank` | none | Beszel sends no recovery for SMART and ZFS. Those alerts stay open until you resolve them in Uptimeify. Several unhealthy containers on one system share one alert, because Beszel's recovery also covers the whole system. ## Default field mapping | Beszel field | Normalized field | |---|---| | `title` | Title, verbatim | | `title` | Status: `below threshold` (battery: `above threshold`), `is up`, `recovered` and `containers are healthy` resolve the alert, everything else keeps it open | | `title` | Host: the Beszel system name, also when it contains spaces | | `title` | Dedup key: system plus alert type, the same for the firing and the recovery notification | | `message` | Link back to the system in Beszel (the URL Beszel appends to every message) | | `message` | Custom field `details`, the message without the link (for example `CPU averaged 91.20% for the previous 10 minutes.`) | ### Severity map | Beszel alert | Uptimeify severity | |---|---| | SMART failure, ZFS pool `FAULTED`, `OFFLINE`, `UNAVAIL`, `REMOVED` or `SUSPENDED` | `sev1` | | Connection down, failed services, ZFS pool `DEGRADED` | `sev2` | | SMART warning | `sev3` | | Everything else | The source's default severity | ## Sample payload ```json { "title": "backend1 CPU above threshold", "message": "CPU averaged 91.20% for the previous 10 minutes.\n\nhttps://beszel.example.com/system/x8k2m4p9q1w7e3r" } ``` You can send this exact payload against your source's mapping from the **Payload Mapping** tab in the dashboard to verify th…
### Custom webhook
URL: https://docs.uptimeify.io/api/incident-management/alert-sources/custom-webhook
Description: Send alerts from any tool that can POST JSON to Uptimeify Incident Management, and define your own field mapping in the dashboard.
Summary: The **Custom webhook** preset is the starting point for any monitoring or alerting tool that doesn't have a dedicated preset: a firewall appliance, an internal script, a niche SaaS product, anything that can send an HTTP `POST` request with a JSON body. Unlike the other presets, it ships with only a minimal default mapping; you fill in the rest yourself once you can see your tool's real payload shape. ## 1. Create the alert source in Uptimeify Go to **Incident Management → Alert Sources → New**, pick the **Custom webhook** preset, name it, and create it. On the success screen, copy the ingest URL (`https:///api/im/ingest/`). It is shown once and never displayed again in cleartext. If you lose it, rotate the token from the source's **Settings** tab. ## 2. Point your tool at the ingest URL Configure your tool's webhook/notification target to send an HTTP `POST` request with a JSON body to the ingest URL, whenever it fires or resolves an alert. There is no fixed request schema on the receiving end. Send whatever your tool produces. ```bash curl -X POST "https:///api/im/ingest/" \ -H "Content-Type: application/json" \ -d '{ "title": "Disk usage above 90% on db-primary", "status": "open" }' ``` ## 3. Adjust the field mapping to your payload The default mapping only extracts a title and a status: reasonable defaults for a generic payload, but almost certainly not everything you want: 1. Send a real (or representative test) payload from your tool once, so you can see its exact field names. The source's **Live activity** view on the alert source detail page shows the most recent raw payloads received. 2. Open the source's **Payload Mapping** tab and edit the selectors: add `severity`, `host`, and `dedupKey` selectors pointing at your payload's actual field names (dot/bracket paths like `data.host.name` or `alerts[0].id` are supported, and `a || b` fallback chains for fields that aren't always present). Add a `severityMap` if your tool sends its own severity vocabulary, so it maps onto Uptimeify's `sev1` to `sev4` scale. 3. Save, then use the **Payload Mapping** tab's test panel to send a sample payload through your edited mapping and confirm the extracted title/severity/status/host look right before relying on it for real alerts. ## Payloads without a status field (regex) Some tools only send free text: Beszel, Uptime Kuma's generic webhook, Healthchecks.io, Gatus. There is no status field and no stable alert id, and the firing and the recovering title differ. Any selector can cut a value out of text with `field =~ /pattern/`, the same syntax as the [email source](/api/incident-management/alert-sources/email). The value is the first group in brackets, or the whole match if the pattern has none. No match counts as "not present", so the next candidate of an `a || b` chain is tried. Flags `i`, `m`, `s` and `u` are allowed; only the first 4,096 characters of a field are searched, and a pattern that repeats a group which itself repeats (`(a+)+`) never matches. Example for [Beszel](https://beszel.dev) (generic webhook, `template=json`), which sends `{"title": "backend1 CPU above threshold", "message": "..."}` and, on recovery, `"backend1 CPU below threshold"`: | Selector | Value | |---|---| | `title` | `title` | | `status` | `title =~ /(below threshold\|is up)/` with `resolveValues`: `below threshold`, `is up` | | `dedupKey` | `title =~ /^(.+) (?:above\|below) threshold$/ \|\| title =~ /^Connection to (.+) is/` | A firing and its recovery then share one dedup key (`backend1 CPU`, or `backend1` for connection alerts), and the recovery resolves the incident. For Beszel itself, the [Beszel preset](/api/incident-management/alert-sources/beszel) is ready to use and also covers containers, services, battery, SMART and ZFS. ## Default field mapping | Selector | Normalized field | Notes | |---|---|---| | `title \|\| message` | Title | Tries `title` first, falls back to `message` | | `status` | Status: values…
### Datadog
URL: https://docs.uptimeify.io/api/incident-management/alert-sources/datadog
Description: Send Datadog Monitor alerts to Uptimeify Incident Management via a Datadog webhook integration, pre-mapped to title, alert type, and transition state.
Summary: Uptimeify's Datadog preset maps Datadog's Monitor webhook notification payload directly: alert title, alert type, transition state, and hostname are pre-mapped. ## 1. Create the alert source in Uptimeify Go to **Incident Management → Alert Sources → New**, pick the **Datadog** preset, name it, and create it. On the success screen, copy the ingest URL (`https:///api/im/ingest/`). It is shown once and never displayed again in cleartext. If you lose it, rotate the token from the source's **Settings** tab. ## 2. Add a Webhooks integration in Datadog 1. In Datadog, go to **Integrations → Webhooks** and click **New**. 2. Give the webhook a name (for example `uptimeify`) and set the **URL** to the ingest URL you copied in step 1. 3. Set the **Payload** to Datadog's default monitor-notification payload, unchanged, since Uptimeify's preset expects the standard fields (`alert_id`, `alert_title`, `alert_type`, `alert_transition`, `hostname`, …). If you have customized the payload template on this webhook before, reset it to Datadog's default, or edit your Uptimeify source's **Payload Mapping** tab to match your custom fields instead. 4. Save the webhook. ## 3. Notify the webhook from your monitors Datadog only calls a webhook integration when a monitor's notification message references it explicitly: 1. Open (or create) a Datadog **Monitor**. 2. In the **Notify your team** section of the monitor's message, add `@webhook-uptimeify` (replace `uptimeify` with whatever name you gave the webhook in step 2). 3. Save the monitor. Datadog now calls the webhook on every state transition (Triggered, Warn, Recovered, …) the monitor's notification rules cover. Repeat steps 2 and 3 for every monitor you want to appear in Uptimeify, or add `@webhook-uptimeify` to a notification default your monitors already share. ## Default field mapping | Datadog field | Normalized field | |---|---| | `alert_title` | Title | | `alert_type` | Severity (via the map below) | | `alert_transition` | Status: `Recovered` resolves the alert, anything else keeps it open | | `hostname` | Host | | `url` | Link back to the event in Datadog | | `alert_metric`, `tags` | Custom fields `metric`, `event_tags`, shown as details on the incident | | `alert_id` | Dedup key: groups notifications for the same monitor event | ### Severity map | Datadog `alert_type` | Uptimeify severity | |---|---| | `error` | `sev1` | | `warning` | `sev3` | | `success` | `sev4` | | `info` | `sev4` | ## Sample payload This is the shape of payload Uptimeify's Datadog preset expects: ```json { "id": "4707056510925961466", "alert_id": "1234567", "alert_title": "[Triggered] High CPU usage on host web-01", "alert_type": "error", "alert_transition": "Triggered", "alert_status": "Alert", "alert_metric": "system.cpu.user", "date": "1752739200000", "event_type": "metric_alert_monitor", "hostname": "web-01.prod.example.com", "org": { "id": "123456", "name": "Example Org" }, "priority": "normal", "tags": "env:prod,service:web", "title": "[Triggered] High CPU usage on host web-01", "url": "https://app.datadoghq.com/event/event?id=4707056510925961466" } ``` You can send this exact payload against your source's mapping from the **Payload Mapping** tab in the dashboard to verify the setup before wiring up a real monitor.
### Email
URL: https://docs.uptimeify.io/api/incident-management/alert-sources/email
Description: Forward or route alert emails from any monitoring tool, ticketing system, or mailbox to a dedicated inbound address, and turn them into incidents automatically.
Summary: The **Email** alert source turns emails you forward or route to a dedicated inbound address into incidents. Use it for any monitoring or alerting tool that can only notify by email (no webhook option), or for anywhere alerts already land in an inbox: a shared ops mailbox, a legacy paging system, a vendor that only offers email notifications. Unlike the webhook presets on this section's other pages, an Email source has no JSON payload. It parses the email's subject and plain-text body with its own selector language (below), not the dot/bracket `Selector` paths those guides use. ## 1. Create the alert source in Uptimeify Go to **Incident Management → Alert Sources → New** and pick the **Email** option (alongside the webhook presets), name it, and create it. On the success screen, copy the inbound address. It has the shape `@alerts.uptimeify.io` and is shown once, never displayed again in cleartext. If you lose it, rotate the token from the source's **Settings** tab to get a fresh address. ## 2. Point your alerts at the address There is no fixed sender or vendor. Anything that can deliver a plain-text email works: - Set the address as the notification/contact target in a monitoring tool that only supports email alerting. - Add a forwarding rule in your mailbox (Gmail, Outlook, a shared ops alias, …) that forwards matching alert emails to it. - Point an existing mail-routing rule or relay at it, if alerts already flow through one. Only the **plain-text body** is read. An HTML-only email with no plain-text part resolves to an empty body for selector purposes. The subject is still available. ## Default field mapping (zero configuration) A freshly created Email source works with no further setup, using these defaults: | Field | Default source | Notes | |---|---|---| | Title | Subject header, verbatim | | | Status | `open`, unless the subject contains the whole word `resolved`, `recovered`, or `cleared` (case-insensitive) | Only the **subject** is scanned for these, never the body, so a firing alert's body prose (e.g. "checks are not ok") can never be mistaken for a resolution | | Severity | The source's configured default severity | Every email uses it until you add a `severity` selector + `severityMap` | | Host | Empty | Until you add a `host` selector | | Dedup key | A deterministic hash of the title + sender address | Until you add a `dedupKey` selector | ## The email selector language Email selectors are a small, separate syntax from the JSON `Selector` paths used by webhook sources. An email has no JSON structure to walk: | Selector | Resolves to | |---|---| | `subject` | The email's Subject header, verbatim | | `body` | The plain-text body, verbatim | | `body.line(N)` | The Nth line of the plain-text body, 1-indexed (`body.line(1)` is the first line) | | `subject =~ /pattern/` | Regex match against the subject: the first capturing group `(...)` if the pattern has one, otherwise the whole match | | `body =~ /pattern/` | Same, matched against the plain-text body | A selector may chain fallbacks with `||`, same convention as the webhook `Selector` paths: the first candidate that resolves to a non-empty value wins: ``` subject =~ /Status: (\w+)/ || body.line(1) ``` A missing field, an out-of-range line, or an invalid/non-matching regex all resolve to nothing rather than erroring. A malformed or unexpected email is normal, reachable input, not a bug. ## Customizing the mapping There is currently no dedicated mapping editor in the dashboard for Email sources (the **Payload Mapping** tab's selector editor targets the JSON webhook shape). To configure selectors, use the [Alert Sources API](/api/incident-management/alert-sources-api) with an organization-wide API token: 1. `GET /api/im/sources/:id` to read the source's current `payloadMapping`. You need the FULL object back, not just the part you're changing (see the warning below). 2. `PATCH /api/im/sources/:id` with the complete `payloadMapping`, adding or editing an `emailSele…
### Grafana Alerting
URL: https://docs.uptimeify.io/api/incident-management/alert-sources/grafana-alerting
Description: Send Grafana Alerting notifications to Uptimeify Incident Management via a Webhook contact point, mapped from the alert group's first alert.
Summary: Uptimeify's Grafana preset maps Grafana Alerting's webhook contact-point payload directly: the alert name, severity label, status, and instance are pre-mapped from the first alert in the notification group. ## 1. Create the alert source in Uptimeify Go to **Incident Management → Alert Sources → New**, pick the **Grafana** preset, name it, and create it. On the success screen, copy the ingest URL (`https:///api/im/ingest/`). It is shown once and never displayed again in cleartext. If you lose it, rotate the token from the source's **Settings** tab. ## 2. Add a Webhook contact point in Grafana 1. In Grafana, go to **Alerting → Contact points** and click **Add contact point**. 2. Give it a name (for example `uptimeify`) and set **Integration** to **Webhook**. 3. Set the **URL** to the ingest URL you copied in step 1, and leave the **HTTP method** as `POST`. 4. Leave the payload as Grafana's default webhook body. Uptimeify's preset reads the standard fields (`alerts[]`, `status`, `commonLabels`, …) it already sends. Save the contact point. ## 3. Route alerts to the contact point A contact point only receives notifications once a **notification policy** routes to it: 1. Go to **Alerting → Notification policies**. 2. Either point the **default policy** at your new contact point (every alert routes there), or add a nested policy with a label matcher (for example `severity =~ ".+"`) that routes matching alerts to it. 3. Save. Grafana now calls the webhook whenever an alert rule matching that policy fires or resolves. ## Default field mapping Grafana groups alerts into one notification; the preset reads all of these from the **first alert** (`alerts[0]`) in that group, falling back to the group-level `title` for the title field: | Grafana field | Normalized field | |---|---| | `alerts[0].labels.alertname` (falls back to the top-level `title`) | Title | | `alerts[0].labels.severity` | Severity (via the map below) | | `alerts[0].status` | Status: `resolved` resolves the alert, anything else (typically `firing`) keeps it open | | `alerts[0].labels.instance` | Host | | `alerts[0].panelURL` (falls back to `dashboardURL`, `generatorURL`, top-level `externalURL`) | Link back to Grafana | | `alerts[0].annotations.summary` (falls back to `message`), `alerts[0].annotations.description`, `alerts[0].valueString` | Custom fields `summary`, `description`, `item_value`, shown as details on the incident | | `alerts[0].fingerprint` | Dedup key: Grafana's own stable per-alert identity | ### Severity map Grafana has no built-in `severity` label. This only works if your alert rules set one (for example via a `severity` label on the rule): | Grafana `severity` label | Uptimeify severity | |---|---| | `critical` | `sev1` | | `high` | `sev2` | | `warning` | `sev3` | | `info` | `sev4` | If your alert rules don't set a `severity` label, every alert falls back to the source's configured default severity. ## Sample payload This is the shape of payload Uptimeify's Grafana preset expects: ```json { "receiver": "uptimeify-webhook", "status": "firing", "orgId": 1, "alerts": [ { "status": "firing", "labels": { "alertname": "HighCPU", "severity": "critical", "instance": "server1:9090" }, "annotations": { "summary": "CPU usage above 90% on server1" }, "startsAt": "2026-07-17T12:00:00Z", "endsAt": "0001-01-01T00:00:00Z", "generatorURL": "https://grafana.example.com/alerting/grafana/abc123/view", "fingerprint": "8f3b1c9a2d4e5f60", "silenceURL": "https://grafana.example.com/alerting/silence/new", "dashboardURL": "https://grafana.example.com/d/abc123", "panelURL": "https://grafana.example.com/d/abc123?viewPanel=2" } ], "groupLabels": { "alertname": "HighCPU" }, "commonLabels": { "alertname": "HighCPU", "severity": "critical" }, "commonAnnotations": { "summary": "CPU usage above 90% on server1" }, "externalURL": "https://grafana.example.com/", "version": "1", "groupKey": "{}/{alertname=\"HighCPU\"}", "truncatedAlerts": 0, "title": "[FIRING:1] HighCPU", "…
### Prometheus Alertmanager
URL: https://docs.uptimeify.io/api/incident-management/alert-sources/prometheus-alertmanager
Description: Send Prometheus Alertmanager notifications to Uptimeify Incident Management via a webhook receiver, mapped from commonLabels and the first alert.
Summary: Uptimeify's Alertmanager preset maps Alertmanager's `webhook_config` notification payload directly: the summary/alertname, severity label, status, and instance are pre-mapped. ## 1. Create the alert source in Uptimeify Go to **Incident Management → Alert Sources → New**, pick the **Prometheus Alertmanager** preset, name it, and create it. On the success screen, copy the ingest URL (`https:///api/im/ingest/`). It is shown once and never displayed again in cleartext. If you lose it, rotate the token from the source's **Settings** tab. ## 2. Add a webhook receiver in Alertmanager Add a receiver to your `alertmanager.yml` pointing at the ingest URL: ```yaml receivers: - name: uptimeify webhook_configs: - url: "https:///api/im/ingest/" send_resolved: true ``` `send_resolved: true` is required. Without it, Alertmanager never calls the webhook when an alert resolves, so incidents in Uptimeify would stay open forever even after the underlying problem clears. ## 3. Route alerts to the receiver Reference the receiver from a route in the same file (either as the default route, or a nested route matching specific labels): ```yaml route: receiver: uptimeify # ...existing routing tree, or a nested `routes:` matcher instead of the default ``` Reload or restart Alertmanager to pick up the config change (`amtool check-config` first is a good sanity check). ## Default field mapping Alertmanager groups multiple firing alerts into one notification; the preset reads the title and instance from the **first alert** (`alerts[0]`) in that group, and severity from the group-level `commonLabels`: | Alertmanager field | Normalized field | |---|---| | `alerts[0].annotations.summary` (falls back to `commonLabels.alertname`) | Title | | `commonLabels.severity` | Severity (via the map below) | | `status` (top-level) | Status: `resolved` resolves the alert, anything else (typically `firing`) keeps it open | | `alerts[0].labels.instance` | Host | | `alerts[0].generatorURL` (falls back to top-level `externalURL`) | Link back to the Prometheus expression | | `alerts[0].annotations.summary` (falls back to `commonAnnotations.summary`), `alerts[0].annotations.description` | Custom fields `summary`, `description`, shown as details on the incident | | `alerts[0].fingerprint` | Dedup key: Alertmanager's own stable per-alert identity | ### Severity map This only works if your alert rules set a `severity` label: | Alertmanager `severity` label | Uptimeify severity | |---|---| | `critical` | `sev1` | | `warning` | `sev3` | | `info` | `sev4` | Any other value, or a missing `severity` label, falls back to the source's configured default severity. There is no `sev2` mapping for Alertmanager, since its own severity convention is typically just `critical`/`warning`/`info`. ## Sample payload This is the shape of payload Uptimeify's Alertmanager preset expects: ```json { "version": "4", "groupKey": "{}:{alertname=\"InstanceDown\"}", "truncatedAlerts": 0, "status": "firing", "receiver": "uptimeify-webhook", "groupLabels": { "alertname": "InstanceDown" }, "commonLabels": { "alertname": "InstanceDown", "severity": "critical", "job": "node" }, "commonAnnotations": { "summary": "Instance 10.0.0.5:9100 down" }, "externalURL": "http://alertmanager.example.com:9093", "alerts": [ { "status": "firing", "labels": { "alertname": "InstanceDown", "severity": "critical", "instance": "10.0.0.5:9100", "job": "node" }, "annotations": { "summary": "Instance 10.0.0.5:9100 down", "description": "10.0.0.5:9100 has been down for more than 5 minutes." }, "startsAt": "2026-07-17T12:00:00.000Z", "endsAt": "0001-01-01T00:00:00Z", "generatorURL": "http://prometheus.example.com:9090/graph?g0.expr=up%7Bjob%3D%22node%22%7D+%3D%3D+0", "fingerprint": "5b6e6e8f7a1c9d3e" } ] } ``` You can send this exact payload against your source's mapping from the **Payload Mapping** tab in the dashboard to verify the setup before reloading Alertmanager with the real receiver.
### Report form
URL: https://docs.uptimeify.io/api/incident-management/alert-sources/report-form
Description: A link that lets staff, suppliers or customers report an incident or a security concern without a login. Each report becomes an alert in Incident Management.
Summary: The **Report form** alert source gives you a link to a simple web form. Anyone you hand the link to, staff, suppliers, customers, can report something that looks wrong without an account and without technical knowledge. Each report opens an alert in the source's team, with the same routing, grouping and escalation as any other source. It covers the requirement of NIS-2 Implementing Regulation (EU) 2024/2690, Annex 3.3, that staff and relevant third parties can report incidents and suspicious events. ## 1. Create the source Go to **Incident Management → Alert Sources → New**, pick **Report form**, name it and choose the team. On the success screen, copy the link. It has the shape `https://uptimeify.io/report/` (the German form: `/de/report/`) and is shown once. If you lose it, rotate the token from the source's **Settings** tab; the old link keeps working for 7 days. Share the link wherever people will find it: the intranet, the supplier portal, your security policy, an email signature. ## 2. What the form asks | Field | Required | Becomes | |---|---|---| | What happened? | Yes, 10 to 4000 characters | The alert title (its first eight words) and the `description` field | | Since when? | No, free text | The `since` field | | Who is affected? (nobody, a few, many) | No | The suggested severity and the `impact` field | | Do you suspect an attack? (yes, no, don't know) | No, defaults to "don't know" | The `suspectedAttack` field | | Name, email | No | Only the alert's raw payload, under `reporter` | The page shows only your organization's name. It is not indexed by search engines and sends no referrer. ## Severity The severity is a suggestion from the reporter's own estimate, your team re-rates it during triage: | Who is affected? | Severity | |---|---| | Nobody | `sev4` | | A few people | `sev3` | | Many people | `sev2` | | Not answered | `sev3` | Every report opens its own alert (`dedupKey` `form:`), so two people reporting the same thing are two voices, not a duplicate. ## Abuse protection The link is public by design, so the form carries the same protection as other public forms on uptimeify.io: a hidden honeypot field, a minimum fill time, and a quota of 3 reports per sender per hour and 30 reports per form per hour. The sender's IP address is only used as a daily changing pseudonym for the quota and is not stored with the report. A discarded submission gets the same confirmation as an accepted one. The form's link only works with the form. The [webhook endpoint](/api/incident-management/ingest-webhook) answers a form token with `404`, and HMAC or Bearer authentication do not apply to a form source. ## Personal data Name and email are optional and the form says so. They stay in the alert's raw payload, which is cleared after 90 days like every other source's raw payload. The fields `description`, `since`, `impact` and `suspectedAttack` are part of the alert like any mapped field. For the reports, your organization is the controller and Uptimeify processes them on your behalf under the data processing agreement. ## Mapping A form source always has this fixed mapping; a `payloadMapping` sent when creating it is ignored. Test it with [test-mapping](/api/incident-management/alert-sources-api) by passing a `payload` (a form source has no sample): ```json { "title": "title", "severity": "severity", "severityMap": { "sev1": "sev1", "sev2": "sev2", "sev3": "sev3", "sev4": "sev4" }, "dedupKey": "dedupKey", "custom": { "description": "description", "since": "since", "impact": "impact", "suspectedAttack": "suspectedAttack" } } ```
### Sentry
URL: https://docs.uptimeify.io/api/incident-management/alert-sources/sentry
Description: Send Sentry issue alerts to Uptimeify Incident Management via an internal integration webhook, mapped from the event's level, message, and environment.
Summary: Uptimeify's Sentry preset maps Sentry's issue-alert webhook payload directly: the event message/culprit, level, action, server, issue link, environment and project are pre-mapped. ## 1. Create the alert source in Uptimeify Go to **Incident Management → Alert Sources → New**, pick the **Sentry** preset, name it, and create it. On the success screen, copy the ingest URL (`https:///api/im/ingest/`). It is shown once and never displayed again in cleartext. If you lose it, rotate the token from the source's **Settings** tab. ## 2. Create an internal integration in Sentry Sentry sends issue-alert webhooks through an **internal integration**, not a plain webhook URL field: 1. In Sentry, go to **Settings → Developer Settings → New Internal Integration**. 2. Give it a name (for example `Uptimeify`). 3. Enable the **Alert Rule Action** toggle, and under **Webhooks** set the **Webhook URL** to the ingest URL you copied in step 1. 4. Save. This creates an alert-rule action you can attach to any alert rule in the organization. ## 3. Attach it to an alert rule 1. Go to **Alerts → Rules**, and create a new rule (or edit an existing one) for the project(s) you want to forward. 2. Under **Then perform these actions**, add **Send a notification via an integration** and select the internal integration you created in step 2. 3. Save the rule. Sentry now calls the webhook whenever the rule's conditions match, for both newly triggered issues and, if the rule includes a resolve condition, resolutions. ## Default field mapping | Sentry field | Normalized field | |---|---| | `data.event.message` (falls back to `data.event.culprit`) | Title | | `data.event.level` | Severity (via the map below) | | `action` (top-level) | Status: `resolved` resolves the alert, anything else (`triggered`, `created`, `ignored`, `assigned`, …) keeps it open | | `data.event.server_name` | Host. No fallback: an environment name like `production` names no system, so an event without `server_name` has no host | | `data.event.web_url` | Link back to the issue in Sentry | | `data.event.environment`, `data.event.project` | Custom fields `environment`, `project`, shown as details on the incident | | `data.event.issue_id` | Dedup key: groups all notifications for the same Sentry issue | ### Severity map | Sentry `level` | Uptimeify severity | |---|---| | `fatal` | `sev1` | | `error` | `sev2` | | `warning` | `sev3` | | `info` | `sev4` | | `debug` | `sev4` | ## Sample payload This is the shape of payload Uptimeify's Sentry preset expects: ```json { "action": "triggered", "data": { "event": { "event_id": "fe208ee2e2e74ae08b3d4b7cdb9b4e3d", "issue_id": "123456789", "level": "error", "culprit": "raven.scripts.runner in main", "message": "This is an example python exception", "platform": "python", "environment": "production", "server_name": "web-01.prod.example.com", "web_url": "https://sentry.io/organizations/example/issues/123456789/", "issue_url": "https://sentry.io/api/0/issues/123456789/" } }, "actor": { "type": "application", "id": "sentry", "name": "Sentry" } } ``` You can send this exact payload against your source's mapping from the **Payload Mapping** tab in the dashboard to verify the setup before wiring up a real alert rule.
### Zabbix
URL: https://docs.uptimeify.io/api/incident-management/alert-sources/zabbix
Description: Send Zabbix trigger alerts to Uptimeify Incident Management via a Webhook media type, using the ready-made media type Uptimeify generates for you.
Summary: Uptimeify's Zabbix preset maps a Zabbix **Webhook** media type's payload directly: trigger name, severity, status, and host are pre-mapped. Uptimeify also gives you a ready-made media type you can import into Zabbix, so you do not have to create it by hand or write the JavaScript yourself. ## 1. Create the alert source in Uptimeify Go to **Incident Management → Alert Sources → New**, pick the **Zabbix** preset, name it, and create it. On the success screen: - Copy the ingest URL (`https:///api/im/ingest/`), shown once. - Use the **download media type** action to save `uptimeify-zabbix-media-type.yaml`. ## 2. Import the media type into Zabbix 1. In Zabbix, go to **Alerts → Media types** (Zabbix 7.x; **Administration → Media types** on 6.x and older) and click **Import**. 2. Select the downloaded `uptimeify-zabbix-media-type.yaml` and confirm. A media type named **Uptimeify** appears. 3. Give it the ingest URL. Either define the global macro `{$UPTIMEIFY.INGEST.URL}` under **Administration → Macros** with the URL from step 1, or open the media type and paste the URL straight into its `ingest_url` parameter. 4. Optional, for the **Open in Zabbix** link on each incident: define the global macro `{$ZABBIX.URL}` under **Administration → Macros** with your Zabbix frontend address, e.g. `https://zabbix.example.com`. Without it, incidents simply carry no link. 5. Enable the media type. Already using an older Uptimeify media type? Import the file again over it. Older versions do not send the IP, item, last value, tags or the event link, and the incident then shows none of them. The ingest URL must be a media type **parameter**. Zabbix resolves macros in parameter values only, never inside the script body, a `{$UPTIMEIFY.INGEST.URL}` written into the JavaScript would be POSTed to as a literal string and no alert would ever arrive. ### What the media type sends The imported media type declares one parameter per field the preset maps, so the payload matches the preset's selectors without any further editing: | Parameter | Zabbix macro | Used for | |---|---|---| | `ingest_url` | `{$UPTIMEIFY.INGEST.URL}` | Where the alert is POSTed | | `event_id` | `{EVENT.ID}` | Dedup key, stays the problem event's id in the recovery message, which pairs the two into one incident | | `event_severity` | `{EVENT.SEVERITY}` | Severity (see map below) | | `trigger_name` | `{EVENT.NAME}` | Title | | `trigger_status` | `{EVENT.STATUS}` | `RESOLVED` resolves the alert, anything else keeps it open | | `host_name` | `{HOST.NAME}` | Host | | `host_ip` | `{HOST.IP}` | Detail: IP of the host interface | | `item_name`, `item_value` | `{ITEM.NAME1}`, `{ITEM.LASTVALUE1}` | Details: the trigger's first item and its last value | | `event_tags` | `{EVENT.TAGS}` | Detail: the event tags, sent as `tag:value · tag:value` | | `trigger_id`, `zabbix_url` | `{TRIGGER.ID}`, `{$ZABBIX.URL}` | The link to the event: `{$ZABBIX.URL}/tr_events.php?triggerid=…&eventid=…` | | `event_source`, `event_value`, `date`, `time` | respective macros | Carried through for context | A macro Zabbix cannot resolve (`*UNKNOWN*`, or `{$ZABBIX.URL}` left undefined) is left out of the payload rather than shown. The script treats HTTP 200/202 as success and throws on anything else, so a failed delivery shows up as a failed alert attempt in Zabbix instead of disappearing silently. A `404` there means the token in your ingest URL matches no alert source. ### Delivery and retries Uptimeify answers within a few seconds: `202` once the alert is stored durably, `503` if it could not be stored. The media type retries **30 times, once a minute**, and gives each attempt **20 seconds**, so an alert survives half an hour in which Uptimeify is unreachable. This matters most for recoveries: Zabbix never resends a recovery on its own, and a lost one leaves the incident open. If you imported the media type before 15 September…
### Analytics
URL: https://docs.uptimeify.io/api/incident-management/analytics
Description: Incident volume, MTTA and MTTR per day, the alerts-to-incidents noise ratio and on-call load per user for a date range, in one call.
Summary: `GET /api/im/analytics` Returns the data behind the Incident Management analytics page for one date range: incident volume with MTTA and MTTR per local day, the daily alert noise, and on-call minutes per user. ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token. Incident Management must be enabled for the organization. ## Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `from` | ISO 8601 | Yes | Start of the range (inclusive). | | `to` | ISO 8601 | Yes | End of the range (exclusive). Must be after `from`, at most 400 days later. | | `tz` | number | No | Your UTC offset in minutes (e.g. `120` for UTC+2). Default `0`, clamped to plus or minus 1440. Used to cut `volumeTrend` into local days. Not an integer: `400`. | ## Example (cURL) ```bash curl "$BASE_URL/api/im/analytics?from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z&tz=120" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "from": "2026-09-01T00:00:00.000Z", "to": "2026-10-01T00:00:00.000Z", "volumeTrend": [ { "day": "2026-09-01T22:00:00.000Z", "count": 4, "mttaMinutes": 3.5, "mttrMinutes": 47.25 }, { "day": "2026-09-02T22:00:00.000Z", "count": 1, "mttaMinutes": null, "mttrMinutes": null } ], "noiseQuote": [ { "day": "2026-09-02", "alerts": 38, "deduped": 29, "incidents": 4 } ], "onCallLoad": [ { "userId": "u_abc123", "userName": "Jana Weber", "minutes": 10080 } ] } ``` | Field | Description | |-------|-------------| | `volumeTrend[].day` | UTC instant of local midnight for that day (shifted by `tz`). Format it in your own time zone. Only days with incidents appear. | | `volumeTrend[].count` | Incidents triggered that day. Test incidents are excluded. | | `volumeTrend[].mttaMinutes` | Average minutes from trigger to acknowledge, over incidents that were acknowledged. `null` if none was. | | `volumeTrend[].mttrMinutes` | Average minutes from trigger to resolve, over resolved incidents. `null` if none was. | | `noiseQuote[]` | Per UTC calendar day (`YYYY-MM-DD`, not shifted by `tz`), summed over all alert sources: inbound `alerts`, `deduped` alerts folded into an open one, and `incidents` opened. Covers every day from the date of `from` through the date of `to`. | | `onCallLoad[]` | On-call minutes per user inside the range, same data as the [on-call report](/api/incident-management/reports#on-call-report). | ## Common errors - `401 Unauthorized` (`unauthorized`) when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) for a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the session has no IM-eligible role - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization - `400 Bad Request` (`imReportRangeRequired`) when `from` or `to` is missing or not a valid date - `400 Bad Request` (`imReportRangeInvalid`) when `from` is not before `to` - `400 Bad Request` (`imReportRangeTooLarge`) when the range exceeds 400 days - `400 Bad Request` (`invalidRequestBody`) when `tz` is not an integer
### Audit Log
URL: https://docs.uptimeify.io/api/incident-management/audit-log
Description: Read the Incident Management audit trail: who created, changed or deleted which team, schedule, source or setting, with the recorded diff. Cursor-paginated.
Summary: `GET /api/im/audit-log` Returns the Incident Management audit trail of your organization, newest first: every create, update and delete on teams, members, schedules, overrides, escalation tiers, alert sources, routing rules, channels and IM settings, with who did it and the recorded change. ## Authentication Requires IM access **and** the organization role `admin`. Editors and responders are refused. An organization-wide API token works if it was created by an organization admin (a token carries the role of the user who created it). Incident Management must be enabled for the organization. ## Query Parameters | Parameter | Type | Description | |-----------|------|-------------| | `entityType` | string | Only this entity type, e.g. `im_team`, `im_team_member`, `im_schedule`, `im_schedule_override`, `im_escalation_tier`, `im_alert_source`, `im_routing_rule`, `im_channel`, `im_incident`, `im_org_settings`. | | `actor` | string | Only entries by this user ID. | | `from` | ISO 8601 | Only entries at or after this instant. An invalid date is rejected with `400`. | | `to` | ISO 8601 | Only entries at or before this instant. An invalid date is rejected with `400`. | | `limit` | number | Page size, a positive integer. Default 50, larger values count as 200. | | `before` | number | Cursor: pass `nextCursor` from the previous page to continue. | | `envelope` | string | `items`: answer as `{ items, nextCursor, hasMore }`. Becomes the default on 2027-01-18. | ## Example (cURL) ```bash curl "$BASE_URL/api/im/audit-log?entityType=im_alert_source&limit=2&envelope=items" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "items": [ { "id": 5812, "entityType": "im_alert_source", "entityId": "7", "action": "update", "diff": { "ingestToken": { "from": "rotated", "to": "rotated" }, "secondaryExpiresAt": { "from": null, "to": "2026-10-16T09:30:00.000Z" } }, "at": "2026-10-09T09:30:00.000Z", "actorUserId": "u_abc123", "actorName": "Jana Weber" }, { "id": 5790, "entityType": "im_alert_source", "entityId": "7", "action": "create", "diff": { "name": "Zabbix production", "type": "zabbix", "teamId": 3, "autoResolve": true }, "at": "2026-10-01T08:00:00.000Z", "actorUserId": "u_abc123", "actorName": "Jana Weber" } ], "hasMore": true, "nextCursor": "5790" } ``` **List form:** with `envelope=items` the page arrives as `{ items, nextCursor, hasMore }`, `nextCursor` as a string. Without it the endpoint still answers the current form (`{ entries, hasMore, nextCursor }`, `nextCursor` as a number), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. | Field | Description | |-------|-------------| | `action` | `create`, `update` or `delete`. | | `diff` | Free-form object recorded with the change, usually `{ field: { from, to } }` for updates. Secrets are never recorded, rotations appear as `"rotated"` or `"set"`. | | `actorUserId`, `actorName` | Who made the change. Both `null` if that user account has been deleted since. | | `hasMore`, `nextCursor` | When `hasMore` is `true`, request the next page with `before=`. `nextCursor` is `null` on the last page. | ## Common errors - `400 Bad Request` (`invalidRequestBody`) when `from` or `to` is not a date, or `limit` or `before` is not a positive integer - `401 Unauthorized` (`unauthorized`) when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) for a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the session has no IM-eligible role - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization - `403 Forbidden` (`imAuditLogAccessDenied`) when the caller's role is not `admin`
### Bulk Update Incidents
URL: https://docs.uptimeify.io/api/incident-management/bulk-update-incidents
Description: Applies one action (acknowledge, resolve, severity, assign) to up to 200 Incident Management incidents at once, with a per-incident result.
Summary: `POST /api/im/incidents/bulk` Applies one action to many incidents, for example to acknowledge or resolve dozens of incidents during a large outage. Every incident runs through exactly the same logic as the single-incident endpoint, with the same side effects (stopping or re-arming escalation, status pages, outbound integrations). Incidents are processed one by one and independently: one failing incident does not undo or block the others, so the request is **not** atomic. ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token, see [Authentication](/api/incident-management#authentication). Incident Management must be enabled for the organization. Every action except `acknowledge` is restricted to the incidents' teams: you must be a member of the team of **every** selected incident, or an organization admin. This is checked for all ids before anything is changed; if any incident is not yours, the whole request is refused with `403` and the offending ids are listed in `data.deniedIncidentIds`. An organization-wide API token passes as an organization admin. ## Request Body | Field | Type | Required | Description | |-------|------|----------|--------------| | `ids` | number[] | Yes | 1 to 200 incident IDs, unique positive integers. | | `action` | string | Yes | One of `acknowledge`, `resolve`, `severity`, `assign`, `team`. | | `payload` | object | Depends on `action` | See below. | | `action` | `payload` | Same as | |----------|-----------|---------| | `acknowledge` | none | [Acknowledge](/api/incident-management/acknowledge-incident#acknowledge). An incident that is already acknowledged counts as `ok`. | | `resolve` | `note` (string, optional, up to 10,000 characters) | [Resolve Incident](/api/incident-management/resolve-incident) | | `severity` | `severity` (required, `sev1` to `sev4`) | [Change Incident Severity](/api/incident-management/incident-severity) | | `assign` | `userId` (required: a user ID, or `null` to remove the role holder), `role` (optional, default `assignee`) | [Assign a role](/api/incident-management/incident-assign#assign-a-role) | | `team` | `teamId` (required) | Not implemented, always answers `501` | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/incidents/bulk" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "ids": [42, 43, 44], "action": "resolve", "payload": { "note": "Upstream provider outage resolved." } }' ``` ## Response `200 OK`, also when some incidents failed. `ok` lists the IDs that were changed, `failed` the others with a `reason`: the `data.code` the single-incident endpoint would have returned (for example `imIncidentNotFound`, `imIncidentAlreadyClosed`, `imIncidentStatusConflict`, `invalidUserId`), or `unknown`. ```json { "ok": [42, 43], "failed": [ { "id": 44, "reason": "imIncidentAlreadyClosed" } ] } ``` ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the session user has no IM-eligible role - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization - `403 Forbidden` (`imTeamMembershipRequired`) when the action is not `acknowledge` and at least one selected incident belongs to a team you are not a member of (and you are not an organization admin); `data.deniedIncidentIds` lists them, nothing was changed - `400 Bad Request` (`invalidRequestBody`) when `ids` is empty, longer than 200, contains duplicates or non-positive-integers, `action` is unknown, or the payload for the action is invalid (missing or unknown `severity`, missing `userId`, unknown `role`, `note` not a string or too long, missing `teamId`) - `501 Not Implemented` (`imBulkActionNotImplemented`) for `action: "team"`; moving incidents between teams is not supported
### Channels
URL: https://docs.uptimeify.io/api/incident-management/channels
Description: List, create, update and delete Incident Management paging channels (webhook, Slack, email), including the write-only handling of webhook URLs and headers.
Summary: `GET /api/im/channels` · `POST /api/im/channels` · `GET /api/im/channels/:id` · `PATCH /api/im/channels/:id` · `DELETE /api/im/channels/:id` A **channel** is a shared paging destination of your organization: a generic webhook, a Slack incoming webhook, or an email address. A channel is either org-wide (`teamId: null`) or belongs to one [team](/api/incident-management/teams). A channel can be set as the organization's fallback channel in the [organization settings](/api/incident-management/org-settings), the last resort when an escalation runs out of tiers. ## Authentication Requires the base IM access every endpoint in this API needs (an IM-eligible role `admin`, `editor` or `responder`, or an organization-wide API token; Incident Management must be enabled for the organization). Reading is open to any IM-eligible role. **Writing** an org-wide channel requires the `admin` role. Writing a team channel requires the `admin` role or team-admin membership of that team. An organization-wide API token runs with the role of the user who created it, so a token created by an organization admin can write every channel. Team-admin membership never applies to a token. ## Channel types and `config` | `type` | Required `config` fields | Optional `config` fields | |--------|--------------------------|--------------------------| | `webhook` | `webhookUrl` | `headers` (object of header name to value) | | `slack` | `webhookUrl` | `headers` | | `email` | `email` | | - `webhookUrl` must be an `http` or `https` URL with a public hostname. Private, loopback and reserved IP addresses, `localhost`, `*.local`, `*.internal`, `home.arpa` and hostnames without a dot are rejected. - `headers` must not set the `Host` header. Header names must be valid HTTP header names, values must not contain a line break or another control character, and the headers the sender sets itself (`Content-Length`, `Transfer-Encoding`, `Connection`, `Keep-Alive`, `Upgrade`, `TE`, `Trailer`, `Expect`, `Proxy-Connection`) are rejected. `Authorization` is allowed. This applies on create and on update. - `config` may be at most 8 KB as JSON. Other keys are stored as sent. - Secret fields of another type are dropped, not stored: `webhookUrl` and `headers` on an `email` channel. Changing `type` to `email` also removes the stored `webhookUrl` and `headers`. **`webhookUrl` and header values are write-only.** They are encrypted at rest and never returned. Every response replaces them: `webhookUrl` is `null` and `hasWebhookUrl` says whether one is stored; `headers` keeps the header names with `null` values and `hasHeaders` says whether any header is stored. ## List channels `GET /api/im/channels` Returns all channels of your organization (org-wide and team channels), sorted by name, with the team name resolved. ### Query Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `envelope` | string | none | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/channels?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ### Response `200 OK` ```json { "items": [ { "id": 9, "organizationId": 1, "teamId": 3, "teamName": "Platform Team", "type": "webhook", "name": "Ops webhook", "config": { "webhookUrl": null, "headers": { "X-Api-Key": null }, "hasWebhookUrl": true, "hasHeaders": true }, "isActive": true, "createdAt": "2026-09-20T10:00:00.000Z", "updatedAt": "2026-09-20T10:00:00.000Z" }, { "id": 10, "organizationId": 1, "teamId": null, "teamName": null, "type": "email", "name": "NOC mailbox", "config": { "email": "noc@example.com" }, "isActive": true, "createdAt": "2026-09-20T10:05:00.000Z", "updatedAt": "2026-09-20T10:05:00.000Z" } ], "total": 2, "page": 1, "perPage": 2 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form…
### Create Incident
URL: https://docs.uptimeify.io/api/incident-management/create-incident
Description: Manually creates an Incident Management incident for a team; escalation arms moments after creation, with the same paging behavior as an alert-sourced incident.
Summary: `POST /api/im/incidents` Creates an incident by hand, outside the alert-ingest pipeline, e.g. for something a human noticed before any monitoring tool did. A manually-created incident is not a lesser incident: escalation tier 1 of the team is armed moments after creation, exactly as for an incident created from an ingested alert. That arming happens after this response is returned, so the response reflects the incident row as it was committed, before escalation starts (see `currentTier` below). ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token, see [Authentication](/api/incident-management#authentication). Incident Management must be enabled for the organization. Creating an incident additionally requires the **write bar** for the target team: an organization `admin`, or a *team admin* of that team (team member with `imRole: "admin"`). An organization-wide API token passes as an organization admin. ## Request Body | Field | Type | Required | Description | |-------|------|----------|--------------| | `teamId` | number | Yes | The team that owns the incident and whose escalation tiers page people. Must belong to your organization. | | `title` | string | Yes | Incident title, not blank, up to 10,000 characters. | | `severity` | string | Yes | One of `sev1`, `sev2`, `sev3`, `sev4`. A manual incident has no alert stream to derive severity from, so it is always created with `severityManual: true`. | | `customerId` | number or null | No | Scopes the incident to a customer. Must belong to your organization if given. | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/incidents" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "teamId": 3, "title": "Database connection pool exhausted", "severity": "sev1" }' ``` ## Response `200 OK`: the newly created incident row (same shape as the `items` of [List Incidents](/api/incident-management/list-incidents), without the enrichment fields). ```json { "id": 42, "organizationId": 1, "teamId": 3, "title": "Database connection pool exhausted", "customerId": null, "primarySourceId": null, "severity": "sev1", "severityManual": true, "status": "triggered", "mergedIntoId": null, "escalationPolicyId": null, "currentTier": null, "escalationEpoch": 0, "escalationCycle": 0, "acknowledgedBy": null, "acknowledgedAt": null, "snoozedUntil": null, "autoResolve": true, "resolvedBy": null, "resolveNote": null, "statuspageUpdate": null, "createdBy": null, "sourceKind": "manual", "isTest": false, "triggeredAt": "2026-07-17T09:12:00.000Z", "resolvedAt": null } ``` `sourceKind` is `manual` and `primarySourceId` is `null`: a manually-created incident has no backing alert source. `createdBy` is the creating user's ID for a browser session and `null` for an API token. Arming the initial escalation and any outbound-integration fan-out happen best-effort after the incident row is committed: the incident is guaranteed to exist even if paging or an outbound integration fails, but such a failure is logged server-side, not surfaced in this response. Because escalation arms after this response is returned, `currentTier` is always `null` here. Use [Get Incident](/api/incident-management/get-incident) to see the tier once escalation has started. ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the session user has no IM-eligible role - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization - `403 Forbidden` (`imTeamWriteDenied`) when you are neither an organization admin nor a team admin of `teamId` - `400 Bad Request` (`invalidRequestBody`) when `teamId` is missing or not a positive integer, `title` is missing, blank or longer than 10,000 characters, `severity` is not one of `sev1` to `sev4`, or `customerId` is present but not a positive integer - `422 Unpro…
### Dismiss Merge Suggestion
URL: https://docs.uptimeify.io/api/incident-management/dismiss-merge-suggestion
Description: Drops a suggestion that an Incident Management incident is the same as an open incident from another source.
Summary: `POST /api/im/incidents/:id/dismiss-merge-suggestion` When an incident is created, Incident Management looks for open incidents from other alert sources of your organization that are probably the same (same service or same host, triggered within 15 minutes) and lists them in `mergeSuggestions` of [Get Incident](/api/incident-management/get-incident). Nothing is merged automatically. This endpoint drops one suggestion when it is wrong; to accept it, use [Merge Incidents](/api/incident-management/merge-incidents) instead. The dismissal is written to the incident timeline (`merge_suggestion_dismissed`, payload `{ targetIncidentId }`) and to the organization audit log. Neither incident is changed otherwise, nobody is notified. ## Authentication Any IM-eligible role or an organization-wide API token, see [Authentication](/api/incident-management#authentication). Same rights as merging: you must be a member of the team of incident `:id` or an organization `admin`. ## Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `targetIncidentId` | integer | Yes | The `incidentId` of the suggestion in `mergeSuggestions`. | ```bash curl -X POST "$BASE_URL/api/im/incidents/43/dismiss-merge-suggestion" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "targetIncidentId": 41 }' ``` ## Response `200 OK`: ```json { "ok": true } ``` ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`imTeamMembershipRequired`) when you are not a member of the incident's team and not an organization `admin` - `400 Bad Request` (`invalidRequestBody`) when `targetIncidentId` is missing, not a positive integer, or the body has other fields - `404 Not Found` (`imIncidentNotFound`) when the incident does not exist or belongs to another organization - `404 Not Found` (`imMergeSuggestionNotFound`) when the incident has no open suggestion for `targetIncidentId` (never suggested, or already dismissed)
### Events Ingest
URL: https://docs.uptimeify.io/api/incident-management/events-ingest
Description: Public alert-ingest endpoint for Incident Management. Post any JSON alert payload from your own monitoring or alerting system; it is queued and processed asynchronously into an incident.
Summary: `POST /api/im/events` Accepts an arbitrary JSON alert payload from your own monitoring or alerting system and queues it for asynchronous processing into Incident Management. This is the primary integration endpoint for pushing alerts from third-party systems. ## Authentication Requires an **organization-wide** API token (`Authorization: Bearer wsm_...`, created without a `customerId`, see [Create Organization Token](/api/api-tokens/create-organization-token)). A customer-scoped token is rejected with `403 Forbidden` (`customerScopedTokenForbidden`). Incident Management must also be activated for the organization, or the request is rejected with `403 Forbidden` (`imNotEnabled`). ## Rate limit 600 requests per minute per organization, not per IP. A monitoring system that fans out across many source IPs shares one quota with its organization. ## Request Body Any JSON object. The payload is stored against an `api`-type alert source that is auto-provisioned for your organization the first time you call this endpoint, and mapped into an alert using that source's field mapping. There is no fixed request schema. Send whatever your alerting system produces. The auto-provisioned source reads these fields by default, the first one present wins: | Alert field | Read from | |-------------|-----------| | title | `title`, `summary`, `subject`, `message`, `alertname`, `labels.alertname` | | severity | `severity`, `level`, `priority`, `labels.severity` | | status | `status`, `state` | | dedup key | `dedup_key`, `dedupKey`, `fingerprint`, `groupKey`, `id` | | host (which system) | `host`, `hostname`, `instance`, `labels.instance` | | url (link back to the origin) | `url`, `link`, `generatorURL` | A source whose mapping you changed keeps your mapping. Limits, enforced before the payload is queued: | Limit | Value | Failure | |-------|-------|---------| | Body size | 256 KB | `413 Payload Too Large` (`payloadTooLarge`) | | JSON nesting depth | 20 levels | `422 Payload too deep` (`payloadTooDeep`) | | Valid JSON object or array | required | `422 Invalid JSON` (`invalidJson`) | An empty request body is treated as `{}`. ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/events" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Database connection pool exhausted", "severity": "critical", "host": "db-primary-01" }' ``` ## Response `202 Accepted`: the alert has been queued, not yet processed. There is no synchronous incident or alert ID in the response. ```json { "accepted": true } ``` ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the session user has no IM-eligible role - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization - `413 Payload Too Large` (`payloadTooLarge`) when the body exceeds 256 KB - `422 Invalid JSON` (`invalidJson`) when the body is not valid JSON, or is a bare value (`5`, `"text"`, `null`) instead of an object or array - `422 Payload too deep` (`payloadTooDeep`) when the parsed JSON nests more than 20 levels - `429 Too Many Requests` when your organization exceeds 600 requests/minute (see `retryAfter` in the response body) - `503 Service Unavailable` (`unavailable`) when the alert could not be stored at all, answered within a few seconds; nothing was accepted, so retry. A `202` means the alert is stored durably, even if our queue is briefly unavailable
### Get Incident
URL: https://docs.uptimeify.io/api/incident-management/get-incident
Description: Returns the full detail of a single Incident Management incident: the incident row plus its alerts, timeline events, and role assignments.
Summary: `GET /api/im/incidents/:id` Returns the full detail of a single incident: the incident row plus its alerts (a safe, redacted view, see below), timeline events in chronological order, and role assignments. ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token, see [Authentication](/api/incident-management#authentication). Incident Management must be enabled for the organization. ## Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/incidents/42" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "id": 42, "organizationId": 1, "teamId": 3, "title": "Database connection pool exhausted", "customerId": null, "primarySourceId": 7, "severity": "sev1", "severityManual": false, "status": "triggered", "mergedIntoId": null, "escalationPolicyId": null, "currentTier": 1, "escalationEpoch": 0, "escalationCycle": 0, "acknowledgedBy": null, "acknowledgedAt": null, "snoozedUntil": null, "autoResolve": true, "resolvedBy": null, "resolveNote": null, "statuspageUpdate": null, "createdBy": null, "sourceKind": "alert", "isTest": false, "category": null, "isNearMiss": false, "triggeredAt": "2026-07-17T09:12:00.000Z", "resolvedAt": null, "serviceId": null, "statuspageRuleApplies": false, "customerName": null, "customerPublicId": null, "monitoringIncidentPublicId": null, "hasReportCase": false, "reportCasePublicId": null, "postmortemStatus": "none", "needsPostmortem": false, "canManagePostmortem": false, "mergeSuggestions": [ { "incidentId": 41, "title": "db-primary-01 unreachable", "reason": "host", "suggestedAt": "2026-07-17T09:12:01.000Z" } ], "alerts": [ { "id": 101, "organizationId": 1, "sourceId": 7, "dedupKey": "db-primary-01:pool-exhausted", "status": "open", "suppressedReason": null, "title": "Database connection pool exhausted", "severity": "sev1", "host": "db-primary-01", "mappedFields": {}, "duplicateCount": 0, "firstSeenAt": "2026-07-17T09:12:00.000Z", "resolvedAt": null, "incidentId": 42 } ], "events": [ { "id": 501, "incidentId": 42, "at": "2026-07-17T09:12:00.000Z", "kind": "alert_received", "actorUserId": null, "actorName": null, "payload": {} }, { "id": 502, "incidentId": 42, "at": "2026-07-17T09:15:00.000Z", "kind": "acknowledged", "actorUserId": "u_abc123", "actorName": "Jane Doe", "payload": {} } ], "assignments": [ { "id": 12, "userId": "u_abc123", "userName": "Jane Doe", "role": "commander", "createdAt": "2026-07-17T09:15:00.000Z" } ], "publicUpdates": [ { "id": 17, "publicId": "6f1d2c3b-4a5e-4f60-8a7b-9c0d1e2f3a4b", "status": "investigating", "body": "We are investigating slow logins.", "createdAt": "2026-07-17T09:20:00.000Z", "createdByUserId": "u_abc123" } ] } ``` `publicUpdates` is the incident's public timeline, oldest first and append-only: one entry per text set through [Update Status Page Text](/api/incident-management/incident-statuspage-update), each with `status` (`investigating`, `identified`, `monitoring`, `resolved`), `body`, `createdAt` and `createdByUserId` (`null` once the user is deleted). Public status pages show it without the user. `statuspageRuleApplies` is `true` when one of the team's status page rules would flip a status page for this incident (a rule for its team whose minimum severity it meets). `statuspageUpdate` is the curated text shown on that page (set it with [Update Status Page Text](/api/incident-management/incident-statuspage-update)). `customerName` and `customerPublicId` name the customer in `customerId`; both are `null` when the incident has no customer. `monitoringIncidentPublicId` is the public id of the Uptimeify monitoring incident this incident was bridged from (source type `uptimeify_monitoring`), for a link to `/dashboard/system/incidents/`. It is `null` for every other source. `mergeSuggestions` lists open incidents from OTHER alert sources of your organization that are probably the same incident: triggered within 15 minutes of this one and either assigned the same [service](/a…
### Assign Incident Roles
URL: https://docs.uptimeify.io/api/incident-management/incident-assign
Description: Sets the holder of an incident role (commander, tech lead, comms, assignee), or adds an extra responder to an Incident Management incident, optionally paging them.
Summary: An incident has four roles: `commander`, `tech_lead`, `comms` and `assignee`. Two endpoints manage who holds them: - [Assign a role](#assign-a-role) sets the **single** holder of a role and replaces whoever held it before. - [Add a responder](#add-a-responder) adds **another** person to a role without removing anyone, and can start paging them. Current role holders are listed in `assignments` of [Get Incident](/api/incident-management/get-incident). Every change is recorded on the incident timeline. To remove a role holder, use the `assign` action of [Bulk Update Incidents](/api/incident-management/bulk-update-incidents) with `userId: null`. ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token, see [Authentication](/api/incident-management#authentication). Incident Management must be enabled for the organization. **Who can be assigned:** the person in `userId` must be a user of your organization. Unless you are an organization admin (an organization-wide API token counts as one), that person must also be a member of the incident's team. ## Assign a role `POST /api/im/incidents/:id/assign` ### Request Body | Field | Type | Required | Description | |-------|------|----------|--------------| | `userId` | string | Yes | User ID of the new role holder. | | `role` | string | Yes | One of `commander`, `tech_lead`, `comms`, `assignee`. | ### Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/incidents/42/assign" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "userId": "MFcTjWmYq2LpzR8vK1sXo", "role": "commander" }' ``` ### Response `200 OK`: the new assignment. ```json { "id": 12, "incidentId": 42, "userId": "MFcTjWmYq2LpzR8vK1sXo", "role": "commander", "createdAt": "2026-07-17T09:15:00.000Z", "user": { "name": "Grace Hopper", "email": "grace@example.com" } } ``` `user.email` is only filled for an organization admin (and therefore a normal organization-wide API token); for every other role it is `null`. ### Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the session user has no IM-eligible role - `403 Forbidden` (`imTeamMembershipRequired`) when you are not a member of the incident's team and not an organization `admin` - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization - `400 Bad Request` (`invalidRequestBody`) when `:id` is not a positive integer, `role` is missing or unknown, or `userId` is missing or blank - `404 Not Found` (`imIncidentNotFound`) when the incident does not exist, or belongs to another organization - `422 Unprocessable Entity` (`invalidUserId`) when `userId` does not exist or is not a user of your organization - `422 Unprocessable Entity` (`imIncidentAssigneeNotOnTeam`) when you are not an organization admin and `userId` is not a member of the incident's team ## Add a responder `POST /api/im/incidents/:id/add-responder` Loops in an additional person, for example a specialist the escalation tiers would never reach. With `notify: true` that person's paging chain starts immediately, at the incident's current tier, with the urgency of the incident's severity. Adding a responder is restricted to the incident's team: you must be a member of the incident's team or an organization admin. With `notify: true` you must be a **team admin** of the incident's team or an organization admin. An organization-wide API token passes both as an organization admin. ### Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `userId` | string | Yes | | User ID of the responder. | | `role` | string | Yes | | One of `commander`, `tech_lead`, `comms`, `assignee`. | | `notify` | boolean | No | `false` | `true` starts paging this person right away. | ### Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/inci…
### Find the Incident for a Monitoring Incident
URL: https://docs.uptimeify.io/api/incident-management/incident-by-monitor
Description: Resolves a monitoring incident id to the Incident Management incident it was bridged into.
Summary: `GET /api/im/incidents/by-monitor/:id` When the monitoring bridge is on (see [organization settings](/api/incident-management/org-settings)), every incident from Uptimeify's own monitoring becomes an alert in Incident Management, grouped into an incident. This endpoint answers which Incident Management incident a given **monitoring** incident ended up in, for example to link from a monitoring incident to its paging and timeline. Only alerts of the organization's own monitoring source count. A custom webhook that happens to send the same dedup key (`monitor:`) is never matched. When the monitoring incident was bridged several times, the newest alert wins. ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token, see [Authentication](/api/incident-management#authentication). Incident Management must be enabled for the organization. ## Path parameters | Parameter | Type | Description | |-----------|------|-------------| | `id` | number | The id of the monitoring incident, as returned by [List Incidents](/api/monitoring/list-incidents) of the monitoring API. | ## Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/incidents/by-monitor/5123" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "incidentId": 1834 } ``` Load the incident itself with [Get Incident](/api/incident-management/get-incident). ## Common errors - `400 Bad Request` (`invalidRequestBody`) when `id` is not a positive number - `401 Unauthorized` when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the caller has no IM-eligible role - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization - `404 Not Found` (`imIncidentNotFound`) when the monitoring incident was not bridged (yet), or belongs to another organization
### Classify Incident
URL: https://docs.uptimeify.io/api/incident-management/incident-classification
Description: Sets the NIS-2 category of an Incident Management incident (availability, security, other) and marks it as a near miss.
Summary: `POST /api/im/incidents/:id/classification` Classifies an incident for NIS-2 reporting (Implementing Regulation (EU) 2024/2690, Annex 3.1): its `category` and whether it was a near miss (`isNearMiss`, an event that could have affected availability, integrity or confidentiality but did not). New incidents start with `category: null` (not classified yet) and `isNearMiss: false`; nothing sets them automatically. Allowed in every status, also after the incident is resolved. Fields you leave out stay unchanged. The change is recorded on the incident timeline as a `classification_changed` event (with `from` and `to` per changed field) and in the organization audit log. It pages nobody and is not sent to status pages or outbound integrations. A request that changes nothing writes nothing and returns the incident as it is. With NIS-2 on, a resolved incident with category `security` always needs a [postmortem](/api/incident-management/postmortems), whatever its severity, and a [report case](/api/incident-management/report-cases) linked to it suggests the criterion `malicious_unauthorized_access`. ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token, see [Authentication](/api/incident-management#authentication). Incident Management must be enabled for the organization. You must be a member of the incident's team, or an organization `admin`. ## Request Body | Field | Type | Required | Description | |-------|------|----------|--------------| | `category` | string or null | No* | One of `availability`, `security`, `other`. `null` clears it (not classified). | | `isNearMiss` | boolean | No* | `true` marks the incident as a near miss. | \* At least one of the two. Any other key is rejected. ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/incidents/42/classification" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "category": "security", "isNearMiss": false }' ``` ## Response `200 OK`: the updated incident row (same shape as the `items` of [List Incidents](/api/incident-management/list-incidents), without the enrichment fields). ```json { "id": 42, "teamId": 3, "title": "Suspicious logins on the admin panel", "severity": "sev3", "status": "resolved", "category": "security", "isNearMiss": false } ``` (Shortened; the full row is returned.) ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the session user has no IM-eligible role - `403 Forbidden` (`imTeamMembershipRequired`) when you are not a member of the incident's team and not an organization `admin` - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization - `400 Bad Request` (`invalidRequestBody`) when `:id` is not a positive integer, the body has neither `category` nor `isNearMiss`, `category` is not one of the three values or `null`, `isNearMiss` is not a boolean, or the body has an unknown key - `404 Not Found` (`imIncidentNotFound`) when the incident does not exist, or belongs to another organization
### Comment on Incident
URL: https://docs.uptimeify.io/api/incident-management/incident-comment
Description: Adds a comment to the timeline of an Incident Management incident.
Summary: `POST /api/im/incidents/:id/comment` Adds a free-text comment to the incident's timeline (an event of kind `comment`, visible in `events` of [Get Incident](/api/incident-management/get-incident)). Outbound integrations are notified of the comment, and subscribers of a status page driven by a [status page rule](/api/incident-management/statuspage-rules) may receive it as an update. Comments are accepted on closed incidents too. ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token, see [Authentication](/api/incident-management#authentication). Incident Management must be enabled for the organization. There is no team restriction. ## Request Body | Field | Type | Required | Description | |-------|------|----------|--------------| | `text` | string | Yes | Comment text, not blank, up to 10,000 characters. | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/incidents/42/comment" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "text": "Failover to the replica is running, ETA 10 minutes." }' ``` ## Response `200 OK` ```json { "ok": true } ``` ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the session user has no IM-eligible role - `403 Forbidden` (`imTeamMembershipRequired`) when you are not a member of the incident's team and not an organization `admin` - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization - `400 Bad Request` (`invalidRequestBody`) when `:id` is not a positive integer, or `text` is missing, blank or longer than 10,000 characters - `404 Not Found` (`imIncidentNotFound`) when the incident does not exist, or belongs to another organization
### Count Open Incidents
URL: https://docs.uptimeify.io/api/incident-management/incident-count
Description: Returns the number of open, unacknowledged Incident Management incidents in your organization.
Summary: `GET /api/im/incidents/count` Returns how many incidents are open **and** not yet acknowledged: status neither `resolved` nor `merged`, and no `acknowledgedAt`. This includes incidents that moved from `triggered` straight to `investigating`, `identified` or `monitoring` without an acknowledgement. Test incidents (`isTest: true`) are never counted. A single cheap count, meant for polling a badge or a wallboard; use [List Incidents](/api/incident-management/list-incidents) for anything filtered; its `unacknowledged=true` filter returns exactly the incidents this count covers. ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token, see [Authentication](/api/incident-management#authentication). Incident Management must be enabled for the organization. ## Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/incidents/count" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "count": 4 } ``` ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the session user has no IM-eligible role - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization
### Escalate Incident Now
URL: https://docs.uptimeify.io/api/incident-management/incident-escalate-now
Description: Skips the wait and pages the next escalation tier of a triggered Incident Management incident immediately.
Summary: `POST /api/im/incidents/:id/escalate-now` Pages the next [escalation tier](/api/incident-management/team-tiers) of the incident's team right away instead of waiting for the current tier's timeout. Only valid while the incident is `triggered` (still escalating). The pending jobs of the current tier are cancelled and the next tier (the lowest tier order above the current one) is armed immediately. The tier change itself is applied by the escalation engine moments later, so `currentTier` in the response still shows the tier you escalated from. The incident's timeline gets an `escalated` event with `payload` `{ fromTier, toTier, toTargetName }`. `toTargetName` is the name of what the new tier pages, as it was at that moment: the tier's first schedule, or the team's name for a tier without schedules; `null` when neither exists. ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token, see [Authentication](/api/incident-management#authentication). Incident Management must be enabled for the organization. Restricted to the incident's team: you must be a member of the incident's team (`teamId`) or an organization admin. An organization-wide API token passes as an organization admin. No request body. ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/incidents/42/escalate-now" \ -H "Authorization: Bearer $TOKEN" ``` ## Response `200 OK`: the updated incident row (same shape as the `items` of [List Incidents](/api/incident-management/list-incidents), without the enrichment fields). ```json { "id": 42, "teamId": 3, "title": "Database connection pool exhausted", "severity": "sev1", "status": "triggered", "currentTier": 1, "escalationEpoch": 3 } ``` (Shortened; the full row is returned.) ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the session user has no IM-eligible role - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization - `403 Forbidden` (`imTeamMembershipRequired`) when you are neither a member of the incident's team nor an organization admin - `400 Bad Request` (`invalidRequestBody`) when `:id` is not a positive integer - `404 Not Found` (`imIncidentNotFound`) when the incident does not exist, or belongs to another organization - `422 Unprocessable Entity` (`imIncidentNotEscalating`) when the incident is not `triggered` - `422 Unprocessable Entity` (`imNoFurtherTier`) when the team has no tier above the current one - `409 Conflict` (`imIncidentStatusConflict`) when the incident's escalation state changed concurrently, safe to retry
### Set Incident Service
URL: https://docs.uptimeify.io/api/incident-management/incident-service
Description: Names the service an Incident Management incident affects, or removes it.
Summary: `POST /api/im/incidents/:id/service` Sets the affected [service](/api/incident-management/services) of an incident by hand, or removes it with `null`. Allowed in every status, also after the incident is resolved. Purely descriptive: nobody is paged, no status page or outbound integration is notified. The change is written to the incident timeline (`service_changed`, payload `{ from, to }` with `{ id, name }` or `null`) and to the organization audit log. A call that changes nothing writes nothing. ## Authentication Any IM-eligible role or an organization-wide API token, see [Authentication](/api/incident-management#authentication). You must be a member of the incident's team or an organization `admin`. ## Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `serviceId` | integer \| string \| null | Yes | `id` or `publicId` of a service of the incident's organization; `null` removes the service. | ```bash curl -X POST "$BASE_URL/api/im/incidents/42/service" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "serviceId": 4 }' ``` ## Response `200 OK`: the updated incident row (same shape as the `items` of [List Incidents](/api/incident-management/list-incidents), without the enrichment fields), with `serviceId` set. ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`imTeamMembershipRequired`) when you are not a member of the incident's team and not an organization `admin` - `400 Bad Request` (`invalidRequestBody`) when `serviceId` is missing or neither an integer, a UUID nor `null` - `404 Not Found` (`imIncidentNotFound`) when the incident does not exist or belongs to another organization - `404 Not Found` (`imServiceNotFound`) when the service does not exist or belongs to another organization
### Change Incident Severity
URL: https://docs.uptimeify.io/api/incident-management/incident-severity
Description: Sets the severity of an Incident Management incident by hand. The value then sticks and is no longer derived from its alerts.
Summary: `POST /api/im/incidents/:id/severity` Sets an incident's severity. The incident is marked `severityManual: true`, so new alerts no longer raise or lower it automatically. If the incident is still `triggered`, its pending escalation is cancelled and re-armed at the incident's current tier under the new severity. Status pages driven by a [status page rule](/api/incident-management/statuspage-rules) and outbound integrations are notified of the change. ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token, see [Authentication](/api/incident-management#authentication). Incident Management must be enabled for the organization. Unlike resolve or status changes, this single-incident endpoint has no team restriction. (The `severity` action of [Bulk Update Incidents](/api/incident-management/bulk-update-incidents) does.) ## Request Body | Field | Type | Required | Description | |-------|------|----------|--------------| | `severity` | string | Yes | One of `sev1`, `sev2`, `sev3`, `sev4`. | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/incidents/42/severity" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "severity": "sev2" }' ``` ## Response `200 OK`: the updated incident row (same shape as the `items` of [List Incidents](/api/incident-management/list-incidents), without the enrichment fields), with `severity` set and `severityManual: true`. ```json { "id": 42, "teamId": 3, "title": "Database connection pool exhausted", "severity": "sev2", "severityManual": true, "status": "triggered", "currentTier": 1, "escalationEpoch": 1 } ``` (Shortened; the full row is returned.) ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the session user has no IM-eligible role - `403 Forbidden` (`imTeamMembershipRequired`) when you are not a member of the incident's team and not an organization `admin` - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization - `400 Bad Request` (`invalidRequestBody`) when `:id` is not a positive integer, or `severity` is missing or not one of `sev1` to `sev4` - `404 Not Found` (`imIncidentNotFound`) when the incident does not exist, or belongs to another organization
### Snooze Incident
URL: https://docs.uptimeify.io/api/incident-management/incident-snooze
Description: Pauses escalation and reminders of an open Incident Management incident until a given time (at most 7 days ahead), or ends a snooze early.
Summary: `POST /api/im/incidents/:id/snooze` Pauses an open incident's escalation and reminders until `snoozedUntil`. Pending escalation jobs are cancelled and paging resumes automatically when the snooze ends. Sending `null` (or omitting the field) ends a snooze immediately: a `triggered` incident resumes escalating at its current tier right away. Each call is recorded on the incident timeline. ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token, see [Authentication](/api/incident-management#authentication). Incident Management must be enabled for the organization. Restricted to the incident's team: you must be a member of the incident's team (`teamId`) or an organization admin. An organization-wide API token passes as an organization admin. ## Request Body | Field | Type | Required | Description | |-------|------|----------|--------------| | `snoozedUntil` | ISO 8601 date-time or null | No | When paging resumes. Must be in the future and at most 7 days from now. `null` or omitted clears the snooze. | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/incidents/42/snooze" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "snoozedUntil": "2026-07-17T13:00:00.000Z" }' ``` End a snooze early: ```bash curl -X POST "$BASE_URL/api/im/incidents/42/snooze" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "snoozedUntil": null }' ``` ## Response `200 OK`: the updated incident row (same shape as the `items` of [List Incidents](/api/incident-management/list-incidents), without the enrichment fields). ```json { "id": 42, "teamId": 3, "title": "Database connection pool exhausted", "severity": "sev1", "status": "triggered", "currentTier": 1, "escalationEpoch": 2, "snoozedUntil": "2026-07-17T13:00:00.000Z" } ``` (Shortened; the full row is returned.) ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the session user has no IM-eligible role - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization - `403 Forbidden` (`imTeamMembershipRequired`) when you are neither a member of the incident's team nor an organization admin - `400 Bad Request` (`invalidRequestBody`) when `:id` is not a positive integer, or `snoozedUntil` is not a valid date-time - `400 Bad Request` (`imSnoozeRangeInvalid`) when `snoozedUntil` is not in the future or more than 7 days ahead - `404 Not Found` (`imIncidentNotFound`) when the incident does not exist, or belongs to another organization - `422 Unprocessable Entity` (`imIncidentClosed`) when the incident is `resolved` or `merged`
### Update Status Page Text
URL: https://docs.uptimeify.io/api/incident-management/incident-statuspage-update
Description: Sets the public status page text of an Incident Management incident, shown on status pages that a status page rule switched for this incident.
Summary: `POST /api/im/incidents/:id/statuspage-update` Sets the curated text that status pages show for this incident (`statuspageUpdate` on the incident) and, since 27 October 2026, appends it to the incident's **public timeline** (`publicUpdates` in [Get Incident](/api/incident-management/get-incident)). Every status page a [status page rule](/api/incident-management/statuspage-rules) of the incident's team matches (team and severity) lists the incident with this timeline in every layout from the first update on; without an update it is not listed. Status pages that a rule currently switched because of this incident show the new text in their banner immediately. If the text actually changed, subscribers of the matching pages are notified with an incident update. The timeline is append-only: an entry is never edited or deleted. A new text appends one; the same text again appends one only when you pass `status`; clearing (`null`) only clears `statuspageUpdate`, the timeline keeps what was published. Whether a rule applies to the incident at all is reported as `statuspageRuleApplies` by [Get Incident](/api/incident-management/get-incident); without such a rule the text is stored but appears nowhere. The change is written to the IM audit log. ## Authentication Requires IM access, see [Authentication](/api/incident-management#authentication), **and** status page write access: role `admin` or `editor`. A `responder` cannot use this endpoint. An organization-wide API token passes as an organization admin. Incident Management must be enabled for the organization. There is no team restriction. ## Request Body | Field | Type | Required | Description | |-------|------|----------|--------------| | `update` | string or null | Yes | The public text. Leading and trailing whitespace is trimmed and the text is cut to 5,000 characters. An empty string or `null` clears it. | | `status` | string | No | Phase of the timeline entry: `investigating`, `identified`, `monitoring` or `resolved`. Default: the phase of the incident's last public update, so a follow-up does not fall back to `investigating`; the first update is `investigating`. A resolved incident defaults to `resolved`; after a reopen, a previous `resolved` becomes `investigating`. | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/incidents/42/statuspage-update" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "update": "We are investigating slow logins. Next update in 30 minutes.", "status": "investigating" }' ``` ## Response `200 OK`: the text as stored, and the timeline entry this call appended (`null` when nothing was appended). ```json { "ok": true, "statuspageUpdate": "We are investigating slow logins. Next update in 30 minutes.", "publicUpdate": { "id": 17, "publicId": "6f1d2c3b-4a5e-4f60-8a7b-9c0d1e2f3a4b", "status": "investigating", "body": "We are investigating slow logins. Next update in 30 minutes.", "createdAt": "2026-10-27T09:15:00.000Z", "createdByUserId": "u_abc123" } } ``` ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the session user has no IM-eligible role - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization - `403 Forbidden` (no `data.code`) when your role is neither `admin` nor `editor` - `400 Bad Request` (`invalidRequestBody`) when `:id` is not a positive integer, `update` is missing or neither a string nor `null`, or `status` is not one of the four phases - `404 Not Found` (`imIncidentNotFound`) when the incident does not exist, or belongs to another organization
### Ingest Webhook
URL: https://docs.uptimeify.io/api/incident-management/ingest-webhook
Description: The per-source ingest URL your monitoring tools post alerts to: authentication, limits and status codes.
Summary: `POST /api/im/ingest/:token` Every webhook [alert source](/api/incident-management/alert-sources-api) has its own ingest URL. Your monitoring tool posts its alert JSON there, and the source's mapping turns it into an alert in Incident Management. The [setup guides](/api/incident-management/alert-sources) show the configuration for Zabbix, Datadog, Grafana, Prometheus Alertmanager, Sentry and custom webhooks. To send alerts from your own code with an organization-wide API token instead, use [Events Ingest](/api/incident-management/events-ingest). ## Authentication The token in the URL **is** the credential: treat the full URL like a password. It is returned once when the source is created and when it is [rotated](/api/incident-management/alert-sources-api); after a rotation the previous token keeps working until `secondaryExpiresAt`. A source can additionally require one or both of: - **Bearer token**: `Authorization: Bearer `. - **HMAC signature**: `X-Uptimeify-Timestamp` (Unix seconds) and `X-Uptimeify-Signature` = hex HMAC-SHA256 of `.` with the source's HMAC secret, optionally prefixed `sha256=`. The timestamp must be within 5 minutes of the server time. Every authentication failure, including an unknown token, answers the same `404`, so a wrong token cannot be told from a wrong signature. ## Request - Body: JSON, at most 256 KB, nested at most 20 levels deep. An empty body counts as `{}`. - Content type is not checked; the body is parsed as JSON. - Which fields matter is decided by the source's mapping (preset or custom). The body below fits a custom webhook source mapped to these field names. ### Example (cURL) ```bash curl -X POST "https://uptimeify.io/api/im/ingest/$INGEST_TOKEN" \ -H "Content-Type: application/json" \ -d '{"title":"Disk almost full on db-1","severity":"high","status":"firing","dedup_key":"db-1-disk"}' ``` With HMAC: ```bash TS=$(date +%s) BODY='{"title":"Disk almost full on db-1","status":"firing"}' SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$HMAC_SECRET" -hex | sed 's/^.* //') curl -X POST "https://uptimeify.io/api/im/ingest/$INGEST_TOKEN" \ -H "Content-Type: application/json" \ -H "X-Uptimeify-Timestamp: $TS" \ -H "X-Uptimeify-Signature: sha256=$SIG" \ -d "$BODY" ``` ## Response `202 Accepted`: ```json { "accepted": true } ``` The payload is accepted for processing; mapping, deduplication and paging happen asynchronously. Use the source's [stats and recent payloads](/api/incident-management/alert-sources-api) to see what was made of it. ## Limits - 300 requests per minute per source - 50 MB of request bodies per hour per organization ## Status codes | Status | Body | Meaning | |--------|------|---------| | `202` | `{"accepted":true}` | Accepted. | | `404` | `{"error":"not_found"}` | Unknown or rotated-out token, failed Bearer or HMAC check, the token of a [report form](/api/incident-management/alert-sources/report-form) source, or the organization was deleted. | | `413` | `{"error":"payload_too_large"}` | Body larger than 256 KB. | | `422` | `{"error":"invalid_json"}` | Body is not valid JSON, or not an object or array. | | `422` | `{"error":"payload_too_deep"}` | JSON nested deeper than 20 levels. | | `429` | `data.code` `imIngestRateLimited` | More than 300 requests per minute for this source. | | `429` | `data.code` `imIngestByteBudgetExceeded` | Hourly byte budget of the organization used up. | | `503` | `{"error":"unavailable"}` | Temporarily unable to accept; retry with backoff. Your tool's own retry is the right answer. |
### List Incidents
URL: https://docs.uptimeify.io/api/incident-management/list-incidents
Description: Returns a filtered, paginated list of Incident Management incidents for your organization, by cursor or by page number.
Summary: `GET /api/im/incidents` Returns a filtered list of incidents for your organization, newest first (`triggeredAt` descending, then `id` descending). Each item carries the incident's own fields plus a small, page-level enrichment: the primary assignee, the people on the lifecycle columns, and the incident's alert activity (see [Resolved people](#resolved-people) below). An incident's full alerts, timeline events, and assignments are available on the [Get Incident](/api/incident-management/get-incident) endpoint. ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token, see [Authentication](/api/incident-management#authentication). Incident Management must be enabled for the organization. ## Query Parameters | Parameter | Type | Description | |-----------|------|--------------| | `status` | string, repeatable | Filter by status. One or more of `triggered`, `acknowledged`, `investigating`, `identified`, `monitoring`, `resolved`, `merged`. | | `severity` | string, repeatable | Filter by severity. One or more of `sev1`, `sev2`, `sev3`, `sev4`. | | `category` | string, repeatable | Filter by NIS-2 category. One or more of `availability`, `security`, `other`, `uncategorized` (not classified yet, `category: null`). | | `teamId` | number, repeatable | Filter by owning team ID. | | `customerId` | number, repeatable | Filter by the incident's associated customer ID. | | `sourceId` | number, repeatable | Filter by primary alert source ID. | | `serviceId` | number, repeatable | Filter by affected [service](/api/incident-management/services) ID. | | `assignedUserId` | string | Only incidents where this user ID holds a role (any role). | | `onCall` | boolean (`true`/`false`/`1`/`0`) | `true` restricts to incidents owned by a team the **calling user** is on call for right now; if that user is on call for no team, the page is empty. An API token is never on call itself, so with a token `onCall=true` always returns an empty page. `false` or omitted applies no on-call filter. | | `unacknowledged` | boolean (`true`/`false`/`1`/`0`) | `true` restricts to open incidents that were never acknowledged: status neither `resolved` nor `merged`, no `acknowledgedAt`, and not a test incident (`isTest`). This is exactly the set [Count Open Incidents](/api/incident-management/incident-count) counts, so list and number agree; it also includes incidents that went from `triggered` straight to `investigating`, `identified` or `monitoring`. Works in cursor and page mode (`total` respects it). `false` or omitted applies no filter. | | `from` | ISO 8601 date-time | Only incidents triggered at or after this time. | | `to` | ISO 8601 date-time | Only incidents triggered at or before this time. | | `q` | string | Full-text search on the incident title. Whole words, no prefix matching; web-search syntax is supported (`"quoted phrase"`, `or`, `-excluded`). | | `limit` | number | Page size. Default 50. Values above 100 are capped at 100. | | `cursor` | string | Cursor mode: the `nextCursor` of a previous response. Treat as opaque, round-trip it exactly, do not construct one yourself. | | `page` | number | Page mode: 1-based page number. Cannot be combined with `cursor`. Switches the response to include `total` and `asOf`. | | `asOf` | ISO 8601 date-time | Only incidents triggered at or before this time. In page mode it freezes the result set: if you omit it, the server picks the current time and returns it as `asOf`, pass that value back on every following page so new incidents do not shift the pages. | | `envelope` | string | `items`: answer in the list form with `hasMore` (see below). Becomes the default on 2027-01-18. | A repeatable parameter accepts a repeated query key, e.g. `status=triggered&status=acknowledged`. For single-value parameters, the last occurrence wins. ## Example (cURL) Cursor mode: ```bash curl -X GET "$BASE_URL/api/im/incidents?status=triggered&status=acknowledged&severity=sev1&limit=25&envelope=items"…
### Merge Incidents
URL: https://docs.uptimeify.io/api/incident-management/merge-incidents
Description: Merges one Incident Management incident into another: its alerts and timeline move over, and the merged incident stops escalating.
Summary: `POST /api/im/incidents/:id/merge` Merges the incident `:id` (the source) into `targetIncidentId`, for example when two alerts turned out to be the same outage. In one step: - all alerts and timeline events of the source move to the target, - the source gets status `merged` and `mergedIntoId` set to the target, and its escalation stops, - the source's timeline records `merged`, the target's records `merge_received`. Role assignments stay on the source. A merge cannot be undone through the API. ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token, see [Authentication](/api/incident-management#authentication). Incident Management must be enabled for the organization. Restricted to the source incident's team: you must be a member of the team of incident `:id` or an organization admin. An organization-wide API token passes as an organization admin. ## Request Body | Field | Type | Required | Description | |-------|------|----------|--------------| | `targetIncidentId` | number | Yes | The incident to merge into. Must belong to the same organization, and must be neither `merged` nor `resolved`. | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/incidents/43/merge" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "targetIncidentId": 42 }' ``` ## Response `200 OK`: the updated source incident row (same shape as the `items` of [List Incidents](/api/incident-management/list-incidents), without the enrichment fields) and the target ID. ```json { "source": { "id": 43, "teamId": 3, "title": "Replica lag above threshold", "status": "merged", "mergedIntoId": 42, "currentTier": null, "escalationEpoch": 1 }, "targetIncidentId": 42 } ``` (`source` shortened; the full row is returned.) ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the session user has no IM-eligible role - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization - `403 Forbidden` (`imTeamMembershipRequired`) when you are neither a member of the source incident's team nor an organization admin - `400 Bad Request` (`invalidRequestBody`) when `:id` is not a positive integer, or `targetIncidentId` is missing or not a positive integer - `404 Not Found` (`imIncidentNotFound`) when the source or the target incident does not exist, or belongs to another organization - `422 Unprocessable Entity` (`imIncidentCannotMergeIntoSelf`) when `targetIncidentId` equals `:id` - `422 Unprocessable Entity` (`imIncidentAlreadyMerged`) when the source incident is already `merged` - `422 Unprocessable Entity` (`imIncidentTargetAlreadyMerged`) when the target incident is `merged` - `422 Unprocessable Entity` (`imMergeTargetClosed`) when the target incident is `resolved`
### My On-Call Status
URL: https://docs.uptimeify.io/api/incident-management/my-on-call
Description: Your own on-call duty across all teams: whether you are on call now, upcoming shifts, overrides, and your on-call hours.
Summary: `GET /api/im/me/on-call` · `GET /api/im/me/on-call-stats` The personal view of on-call: whether **you** are on call right now, in which teams, what is coming up, and how many hours you were on call. To see who is on call in general, use [Who Is On Call](/api/incident-management/on-call). ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) with a **user session**. Incident Management must be enabled for the organization. These endpoints describe a person, so an organization-wide API token receives `403` (`imUserSessionRequired`): a token has no shift and no pager. ## My current duty `GET /api/im/me/on-call` Resolved the same way the paging engine resolves it, including team-level overrides. `upcomingShifts` looks two weeks ahead. ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/me/on-call" \ -b "$SESSION_COOKIE" \ -H "Accept: application/json" ``` ### Response ```json { "currentlyOnCall": true, "currentTeams": [ { "teamId": 7, "teamName": "Platform", "tierOrder": 1 } ], "currentShift": { "teamId": 7, "teamName": "Platform", "tierOrder": 1, "startsAt": "2026-10-10T07:00:00.000Z", "endsAt": "2026-10-11T07:00:00.000Z", "scheduleName": "Platform primary" }, "upcomingShifts": [ { "teamId": 7, "teamName": "Platform", "scheduleId": 12, "scheduleName": "Platform primary", "startsAt": "2026-10-17T07:00:00.000Z", "endsAt": "2026-10-18T07:00:00.000Z", "isOverride": false } ], "myOverrides": [ { "id": 91, "teamId": 7, "teamName": "Platform", "scheduleId": 12, "type": "offline", "startsAt": "2026-10-12T18:00:00.000Z", "endsAt": "2026-10-12T22:00:00.000Z", "coveredBy": [{ "userId": "u_8f2", "name": "Mara" }] } ], "degraded": false } ``` | Field | Description | |-------|-------------| | `currentlyOnCall` | Whether you are paged for new incidents right now in at least one team. | | `currentTeams` | Teams you are on call in now. `tierOrder` is the lowest tier you are in, the one that is paged first. | | `currentShift` | The running duty with its real start and end, across back-to-back shifts and overrides. When you are on call in several teams, the one that runs longest. `endsAt` is the same value as `shiftEndsAt` of [`GET /api/im/on-call`](/api/incident-management/on-call) for you in that team (on call in several tiers of a team: the tier whose duty runs longest), computed in the same place. `startsAt` is `null` when the duty began more than two weeks ago, `endsAt` is `null` when it does not end within 90 days (there `shiftEndsAtIsLowerBound` is `true`). `scheduleName` is `null` when the duty comes only from a team-level override. `null` when you are not on call. | | `upcomingShifts` | Your shifts starting within the next two weeks. `isOverride` marks shifts that come from an override. | | `myOverrides` | Your own overrides that are running or still ahead (`type` `online` = you take duty, `offline` = you hand it off). For an offline override, `coveredBy` lists who holds the pager meanwhile, every entry is paged in your place; it is empty for online overrides and for an offline override left as a gap. | | `degraded` | `true` when the status of at least one team could not be resolved. `currentlyOnCall` is then a lower bound: treat it as "status incomplete", not as "off duty". | ## My on-call hours `GET /api/im/me/on-call-stats` Your on-call time this week, this month and in the last 30 days, each with the previous period of the same kind. ### Query parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tz` | string | No | IANA time zone, e.g. `Europe/Berlin`. Decides where a week (Monday 00:00) and a month (1st, 00:00) begin. Unknown or missing: `UTC`. | ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/me/on-call-stats?tz=Europe/Berlin" \ -b "$SESSION_COOKIE" \ -H "Accept: application/json" ``` ### Response ```json { "timeZone": "Europe/Berlin", "week": { "seconds": 25200, "previousSeconds": 23700 }, "month": { "seconds": 90000, "previousSeconds": 0 }, "last30…
### NIS-2 Settings
URL: https://docs.uptimeify.io/api/incident-management/nis2-settings
Description: Switch NIS-2 report cases on for your organization, set the entity classification and choose the reporting officers.
Summary: `GET /api/im/nis2/settings` · `PUT /api/im/nis2/settings` Report cases help you meet the NIS-2 reporting deadlines (24 h early warning, 72 h notification, final report after one month). They are off by default. You submit every report yourself in the BSI portal; Uptimeify transmits nothing and never classifies an incident on its own. ## Authentication Session only (dashboard login). API tokens, including organization-wide tokens, are rejected with `403` (`nis2OfficerRequired`). Requires Incident Management access (`admin`, `editor` or `responder`). Reading is open to organization admins and the listed reporting officers, also while report cases are switched off (then admins and the listed reporting officers can still read the settings; only admins can change them). **Updating** requires the `admin` role. ## Get settings `GET /api/im/nis2/settings` ### Example (cURL) ```bash curl "$BASE_URL/api/im/nis2/settings" \ -H "Cookie: $SESSION_COOKIE" \ -H "Accept: application/json" ``` ### Response `200 OK` ```json { "enabled": true, "entityClass": "important", "postmortemMinSeverity": "sev2", "timezone": "Europe/Berlin", "officers": [ { "userId": "u_8f2c", "name": "Jana Weber", "email": "jana.weber@example.com" } ], "canEdit": true } ``` | Field | Description | |-------|-------------| | `enabled` | Report cases are switched on. Default `false`. | | `entityClass` | `important` (important entity), `essential` (essential entity) or `kritis` (operator of critical facilities). `kritis` adds the facility and critical service to the report drafts. | | `postmortemMinSeverity` | Resolved incidents of this severity or higher (`sev1` is the highest) need a [postmortem](/api/incident-management/postmortems); incidents with a report case or category `security` always do. Default `sev2`. | | `timezone` | IANA time zone for quarters and due dates of actions. Default `Europe/Berlin`. | | `officers` | Reporting officers. They receive the deadline reminders. Admins always have access and are not listed. | | `canEdit` | `true` for organization admins. | ## Update settings `PUT /api/im/nis2/settings` Replaces the settings and the officer list; `postmortemMinSeverity` and `timezone` only change when sent. Any other key is a `400`. ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `enabled` | boolean | Yes | Switch report cases on or off. | | `entityClass` | string | Yes | `important`, `essential` or `kritis`. | | `officerUserIds` | string[] | Yes | User IDs of this organization with the role `admin`, `editor` or `responder`, at most 100. Editors assigned to a customer are customer-side and rejected. `[]` clears the list. | | `postmortemMinSeverity` | string | No | `sev1` to `sev4`. Omitted: unchanged. | | `timezone` | string | No | IANA name such as `Europe/Berlin`; an unknown name is a `400`. Omitted: unchanged. | ### Example (cURL) ```bash curl -X PUT "$BASE_URL/api/im/nis2/settings" \ -H "Cookie: $SESSION_COOKIE" \ -H "Content-Type: application/json" \ -d '{ "enabled": true, "entityClass": "kritis", "officerUserIds": ["u_8f2c"] }' ``` ### Response `200 OK`: the saved settings, same shape as the GET response. ## Common errors - `401 Unauthorized` (`unauthorized`) when not signed in - `403 Forbidden` (`imAccessDenied`) for a customer login or a role without Incident Management access - `403 Forbidden` (`nis2OfficerRequired`) for an API token, or a user who is neither admin nor reporting officer - `403 Forbidden` (`nis2AdminRequired`) when updating without the `admin` role - `400 Bad Request` (`invalidRequestBody`) when a field is missing, has the wrong type, `entityClass` or `postmortemMinSeverity` is not an allowed value, `timezone` is not a known IANA time zone, or the body has an unknown key - `400 Bad Request` (`nis2InvalidOfficer`) when an officer is not a user of your organization with the role `admin`, `editor` or `responder`
### Personal Notification Settings
URL: https://docs.uptimeify.io/api/incident-management/notification-settings
Description: How Incident Management reaches you: channels, notification rules per urgency, channels per severity, phone verification, test notifications and your notification log.
Summary: `GET /api/im/notification-settings` · `PATCH /api/im/notification-settings` · `PUT /api/im/notification-settings/channels` · `PUT /api/im/notification-settings/severity` · `POST /api/im/notification-settings/rules` · `DELETE /api/im/notification-settings/rules/:id` · `POST /api/im/notification-settings/verify-phone` · `POST /api/im/notification-settings/verify-phone-confirm` · `POST /api/im/notification-settings/test` · `GET /api/im/notification-settings/caller-ids` · `GET /api/im/notification-settings/logs` When an escalation pages you, these settings decide **how** you are reached. Every endpoint on this page reads and writes the settings of the calling user. An organization admin can also set them for you ([User notification settings](/api/incident-management/user-notification-settings)); the last write wins, and `lastAdminChangeAt` tells you when that happened. Your settings are created on first access, starting from the organization's [default notifications](/api/incident-management/notification-template) if one is set. ## Concepts - **Channels**: `push` (mobile app), `sms`, `voice` and `email`. - **Rules** form your personal notification chain per **urgency** (`high` or `low`): "after `delayMinutes`, notify me via `channel`". A delay of `0` notifies immediately; delays run from 0 to 1440 minutes. The same urgency/delay/channel combination exists at most once. - **Severity filter** (`severityChannels`): per incident severity (`sev1` to `sev4`), which channels may be used. It is stored sparse: a severity or channel that is not listed is **allowed**. `{"sev4": {"sms": false, "voice": false}}` keeps low-severity incidents off your phone and changes nothing else. - **Phone**: `sms` and `voice` are delivered only to a verified phone number in E.164 format (`+` followed by 7 to 15 digits, e.g. `+491701234567`). You can store `sms`/`voice` rules before the number is verified: they wait, and every page in the meantime is logged as skipped with reason `unverified`. Changing the number resets the verification. ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) with a **user session**. Incident Management must be enabled for the organization. Personal settings belong to a person: an organization-wide API token receives `403` (`imAccessDenied`), the log endpoint `403` (`imUserSessionRequired`). ## Get your settings `GET /api/im/notification-settings` ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/notification-settings" \ -b "$SESSION_COOKIE" \ -H "Accept: application/json" ``` ### Response ```json { "id": 31, "phoneNumber": "+491701234567", "phoneVerified": true, "channels": { "push": true, "sms": true, "email": true }, "severityChannels": { "sev4": { "sms": false, "voice": false } }, "rules": [ { "id": 201, "urgency": "high", "delayMinutes": 0, "channel": "push" }, { "id": 202, "urgency": "high", "delayMinutes": 5, "channel": "sms" }, { "id": 203, "urgency": "low", "delayMinutes": 0, "channel": "email" } ], "lastAdminChangeAt": "2026-10-28T09:12:00.000Z", "lastAdminChangeBy": { "id": "usr_admin", "name": "Ada Admin" } } ``` `rules` are sorted by urgency, then delay. `lastAdminChangeAt` is when an organization admin last set these settings (`null` if never); `lastAdminChangeBy` is that admin, `null` if never or the account no longer exists. ## Change phone number or channel switches `PATCH /api/im/notification-settings` ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `phoneNumber` | string or null | No | E.164 number, or `null` to remove it. A new number is unverified until confirmed, and any pending verification code is discarded. Existing `sms`/`voice` rules stay, but are skipped while the number is unverified. | | `channels` | object | No | Channel switches (`push`, `sms`, `voice`, `email` → boolean), merged into the stored ones. | ### Example (cURL) ```bash curl -X PATCH "$BASE_URL/api/im/notification-settings" \ -b "$SESSION_COOKIE" \ -H "Conte…
### Default Notifications
URL: https://docs.uptimeify.io/api/incident-management/notification-template
Description: The organization's default notification chain: what new users start with when their personal notification settings are first created.
Summary: `GET /api/im/notification-template` · `PUT /api/im/notification-template` The default notifications are the chain a person starts with. They are copied into a person's [personal notification settings](/api/incident-management/notification-settings) when those are created, which happens the first time the person (or an admin through [User notification settings](/api/incident-management/user-notification-settings)) opens them. **They are not retroactive**: people who already have settings keep theirs, and everyone can change their own chain afterwards. `sms` and `voice` steps wait until the person has confirmed a phone number. ## Authentication Requires the `admin` role of the organization, with a user session or an organization-wide API token (the token runs with the role of the user who created it). Customer-bound tokens and customer logins are refused. Incident Management must be enabled for the organization. ## Get the default notifications `GET /api/im/notification-template` ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/notification-template" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ### Response ```json { "channels": { "push": true, "sms": true, "voice": false, "email": true }, "rules": [ { "urgency": "high", "delayMinutes": 0, "channel": "push" }, { "urgency": "high", "delayMinutes": 5, "channel": "sms" }, { "urgency": "low", "delayMinutes": 0, "channel": "email" } ], "updatedAt": "2026-10-28T09:12:00.000Z" } ``` Before the first save the answer is `{ "channels": {}, "rules": [], "updatedAt": null }`, and new users start without a chain. ## Set the default notifications `PUT /api/im/notification-template` Replaces the whole template. ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `rules` | array | Yes | The chain, at most 64 steps. Each step `{ "urgency": "high" or "low", "delayMinutes": 0..1440, "channel": "push", "sms", "voice" or "email" }`. Each urgency/delay/channel combination at most once. An empty list (without `channels`) switches the template off. | | `channels` | object | No | The four delivery switches (`push`, `sms`, `voice`, `email` → boolean). Omitted: a channel is on exactly when `rules` has a step for it. | Unknown fields are rejected. ### Example (cURL) ```bash curl -X PUT "$BASE_URL/api/im/notification-template" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"rules":[{"urgency":"high","delayMinutes":0,"channel":"push"},{"urgency":"high","delayMinutes":5,"channel":"sms"},{"urgency":"low","delayMinutes":0,"channel":"email"}]}' ``` ### Response `200 OK`: the template after the write, same shape as the GET response. Every change is recorded in the audit log. ## Common errors - `400 Bad Request` (`invalidRequestBody`) for an invalid body: unknown field, channel or urgency, delay outside 0 to 1440, more than 64 steps, the same urgency/delay/channel twice - `401 Unauthorized` when not authenticated - `403 Forbidden` (`forbidden`) when the caller is not an `admin` of the organization - `403 Forbidden` (`imAccessDenied`) for a customer login or a customer-bound token - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization
### Who Is On Call
URL: https://docs.uptimeify.io/api/incident-management/on-call
Description: Returns who is on call right now in your organization, one entry per team, escalation tier and person, resolved exactly like the paging engine.
Summary: `GET /api/im/on-call` Returns who is on call **right now** in your organization: one entry per team, escalation tier and person. It uses exactly the same resolution as [`GET /api/im/teams/{id}/on-call-now`](/api/incident-management/team-insights#on-call-now) and the paging engine: the [schedule's](/api/incident-management/schedules) rotation computed at request time (not only the materialized shifts), every [schedule override](/api/incident-management/schedule-overrides) (all tiers and tier-scoped), every [team-level override](/api/incident-management/team-overrides) and every concurrent peer. An override you create, edit or delete counts immediately; there is no wait for the shifts to be re-materialized. ## Authentication Requires the base IM access every endpoint in this API needs (an IM-eligible `admin`, `editor`, or `responder` role, or an organization-wide API token; Incident Management must be enabled for the organization). ## Query Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `envelope` | string | none | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ## Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/on-call?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response `200 OK`: one entry per team, tier and person currently on call. A tier with no one covering right now (a gap) is simply absent from the list. It is not returned as `null` or an error. A team without any schedule at all (only team-level overrides) does not appear in this list either, because `scheduleId` cannot be filled; its on-call people are visible via `GET /api/im/teams/{id}/on-call-now`. ```json { "items": [ { "teamId": 3, "tierId": 12, "tierOrder": 1, "scheduleId": 7, "sourceScheduleId": 7, "userId": "MFcTjWmYq2LpzR8vK1sXo", "userName": "Grace Hopper", "userImage": "/api/assets/avatar/MFcTjWmYq2LpzR8vK1sXo", "shiftEndsAt": "2026-07-18T09:00:00.000Z", "shiftEndsAtIsLowerBound": false } ], "total": 1, "page": 1, "perPage": 1 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form (a bare array of the same entries), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. `userImage` is the avatar delivery URL, or `null` when the person has no picture. A self-uploaded picture sits behind an authorizing path on this API and must be requested with the same credentials. | Field | Description | |-------|-------------| | `teamId` | The team. | | `tierId` | The escalation tier the person is on call for. | | `tierOrder` | Position of that tier in the team's escalation chain, 1-based. | | `scheduleId` | Legacy field, always set: the schedule the person comes from, else the tier's first schedule, else the team's first schedule. Use `sourceScheduleId` for the exact value. | | `sourceScheduleId` | The schedule whose rotation and overrides put the person on call, or `null` when only a team-level override does. | | `userId`, `userName`, `userImage` | The person on call. | | `shiftEndsAt` | End of the person's uninterrupted duty in this tier: the next moment they are no longer on call. Rotation periods in which the same person is on again right after, back-to-back shifts and overrides are crossed, so a one-person schedule running until 31 December reports 31 December, not the end of the current rotation period. An override that takes the duty away ends it at the override's start. | | `shiftEndsAtIsLowerBound` | `true` when the duty does not end within the next 90 days (the look-ahead). `shiftEndsAt` is then only "on call at least until", not an end. `false` for every real end. | The list agrees with `GET /api/im/teams/{id}/on-call-now` and with the set the escalation engine starts from. `shiftEndsAt` is computed in one place for all three on-call endpoints: the same person in the same tier has the same `shiftEnd…
### Organization Settings
URL: https://docs.uptimeify.io/api/incident-management/org-settings
Description: Read and update the Incident Management settings of your organization: monitoring bridge, SMS/voice overage and the fallback channel.
Summary: `GET /api/im/org-settings` · `PATCH /api/im/org-settings` The Incident Management settings of your organization. Both endpoints also work while Incident Management is **not yet enabled**, so you can check the state and prepare the configuration before activation. Activation itself is done in the dashboard, not through this endpoint. ## Authentication Requires an IM-eligible role (`admin`, `editor` or `responder`) or an organization-wide API token. Unlike the rest of this API, Incident Management does not have to be enabled. Reading is open to any IM-eligible role. **Updating** requires the `admin` role. An organization-wide API token runs with the role of the user who created it. ## Get settings `GET /api/im/org-settings` ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/org-settings" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ### Response `200 OK` ```json { "organizationId": 1, "enabled": true, "overageEnabled": false, "monitoringBridge": "both", "fallbackChannelId": 10, "fallbackChannel": null } ``` | Field | Description | |-------|-------------| | `enabled` | Whether Incident Management is active. Read-only here. | | `overageEnabled` | Whether SMS and voice notifications may continue beyond the included quota (billed). Default `false`. | | `monitoringBridge` | How monitoring incidents relate to Incident Management. `both` (default): monitoring incidents also open IM incidents, and classic alerts are still sent. `im_only`: monitoring incidents open IM incidents, classic alerts are suppressed. `classic_only`: no bridge, only classic alerts. | | `fallbackChannelId` | ID of the [channel](/api/incident-management/channels) paged when an escalation runs out of tiers, or `null`. | | `fallbackChannel` | Legacy field, read-only, no effect. Use `fallbackChannelId`. | ## Update settings `PATCH /api/im/org-settings` Partial update. At least one field is required; any other key is a `400`. ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `overageEnabled` | boolean | No | Allow SMS/voice beyond the included quota. | | `monitoringBridge` | string | No | `im_only`, `classic_only` or `both`. | | `fallbackChannelId` | integer \| null | No | An **active** channel of your organization, or `null` to clear. | `enabled` cannot be set here, and the legacy `fallbackChannel` is rejected. ### Example (cURL) ```bash curl -X PATCH "$BASE_URL/api/im/org-settings" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "fallbackChannelId": 10, "monitoringBridge": "im_only" }' ``` ### Response `200 OK`: the updated settings, same shape as the GET response. ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`imAccessDenied`) when using a customer-scoped token, or a session without an IM-eligible role - `403 Forbidden` (`forbidden`) when updating without the `admin` role - `400 Bad Request` (`invalidRequestBody`) when the body is empty or contains an unsupported key (including `enabled`), `overageEnabled` is not a boolean, `monitoringBridge` is not an allowed value, or `fallbackChannelId` is not a positive integer, `null`, or a channel of your organization - `400 Bad Request` (`imChannelInactive`) when `fallbackChannelId` points to an inactive channel - `400 Bad Request` (`imFallbackChannelDeprecated`) when the body contains `fallbackChannel`
### Outbound Integrations
URL: https://docs.uptimeify.io/api/incident-management/outbound-integrations
Description: Forward Incident Management events to Slack, Microsoft Teams, Discord, Jira, PagerDuty, Opsgenie or a generic webhook, and inspect or retry deliveries.
Summary: `GET /api/im/outbound` · `POST /api/im/outbound` · `GET /api/im/outbound/:id` · `PATCH /api/im/outbound/:id` · `DELETE /api/im/outbound/:id` · `GET /api/im/outbound/:id/history` · `POST /api/im/outbound/:id/retry` An **outbound integration** forwards incident events (created, acknowledged, severity or status changed, comment, resolved) to an external system. Unlike a [channel](/api/incident-management/channels), which is a paging target of an escalation, an outbound integration mirrors the incident lifecycle into another tool. An integration is either org-wide (`teamId: null`) or belongs to one [team](/api/incident-management/teams). ## Authentication Requires the base IM access every endpoint in this API needs (an IM-eligible role `admin`, `editor` or `responder`, or an organization-wide API token; Incident Management must be enabled for the organization). Reading (list, detail, history) is open to any IM-eligible role. **Creating, updating, deleting and retrying** require the `admin` role for an org-wide integration, and the `admin` role or team-admin membership for a team integration. An organization-wide API token runs with the role of the user who created it, so a token created by an organization admin passes this bar. Team-admin membership never applies to a token. ## Integration types and `config` | `type` | Required `config` fields | Optional `config` fields | Write-only fields | |--------|--------------------------|--------------------------|-------------------| | `slack` | `webhookUrl` | | `webhookUrl` | | `teams` | `webhookUrl` | | `webhookUrl` | | `discord` | `webhookUrl` | | `webhookUrl` | | `jira` | `baseUrl` (must start with `https://`), `email`, `apiToken`, `projectKey` | `issueType` (default `Task`) | `apiToken` | | `pagerduty_v2` | `routingKey` | | `routingKey` | | `opsgenie` | `apiKey` | `region` (`us` or `eu`, default `eu`) | `apiKey` | | `webhook` | `webhookUrl` | `bearerToken`, `headers` (object of header name to value) | `webhookUrl`, `bearerToken`, `headers` | **Write-only fields are encrypted at rest and never returned.** Every response sets them to `null` and adds a flag per field: `hasWebhookUrl`, `hasApiToken`, `hasRoutingKey`, `hasApiKey`, `hasBearerToken`, and for `webhook` also `hasHeaders` (the whole `headers` object is returned as `null`). Write-only fields of another type are dropped, not stored: a `bearerToken` or `headers` on a `slack` integration is ignored, and so is an `apiKey` on `jira`. URLs are not checked for reachability when you save them. Customer-supplied destinations are checked at send time: a URL that resolves to a private or local address fails the delivery, which then shows up as `failed` in the [delivery history](#delivery-history). ## The `filters` object | Field | Type | Description | |-------|------|-------------| | `teams` | integer[] | Forward only events of incidents of these team IDs. | | `severities` | string[] | Subset of `sev1`, `sev2`, `sev3`, `sev4`. | | `eventKinds` | string[] | Subset of `incident_created`, `acknowledged`, `severity_changed`, `status_changed`, `comment`, `resolved`. | An empty object `{}` forwards everything. For `jira`, an omitted `eventKinds` defaults to `["incident_created"]`, so Jira gets one issue per incident. **Deprecated field:** until 2027-01-18 responses still carry `filters.event_kinds` next to `filters.eventKinds` and request bodies still accept it. Send `eventKinds`; both with different values answer `400` `invalidRequestBody`. ## List integrations `GET /api/im/outbound` Returns all integrations of your organization, sorted by name, secrets redacted. ### Query Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `envelope` | string | none | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/outbound?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` #…
### Postmortems and Follow-up
URL: https://docs.uptimeify.io/api/incident-management/postmortems
Description: Record the root cause, lessons learned and actions after an incident, keep a catalog of causes, and track follow-up.
Summary: `GET /api/im/causes` · `POST /api/im/causes` · `PATCH /api/im/causes/:id` `GET /api/im/incidents/:id/postmortem` · `PUT /api/im/incidents/:id/postmortem` · `POST /api/im/incidents/:id/postmortem/complete` · `POST /api/im/incidents/:id/postmortem/reopen` `GET /api/im/postmortems` · `GET /api/im/postmortems/:id` · `POST /api/im/postmortems/:id/actions` · `PATCH /api/im/postmortems/:id/actions/:actionId` · `DELETE /api/im/postmortems/:id/actions/:actionId` `GET /api/im/follow-up` · `GET /api/im/quarterly-reviews` · `POST /api/im/quarterly-reviews` After an incident is resolved you can write one postmortem for it: summary, impact, root cause, a cause from your organization's catalog, lessons learned and actions. The catalog cause is what makes repeated incidents countable: with NIS-2 switched on, causes that appear in at least two completed postmortems within six months show up as repeated (Art. 4 Implementing Regulation (EU) 2024/2690). **Uptimeify only counts. Whether a repetition is significant is your decision, through a [report case](/api/incident-management/report-cases).** A postmortem keeps a copy of the incident data. When the incident is deleted after 12 months, `incidentId` becomes `null` and the postmortem stays for three years after completion. `:id` under `/incidents` is the numeric ID of an IM incident. `:id` under `/postmortems` and `/causes` and `:actionId` are a `publicId` or a numeric `id`. ## Authentication Postmortems and actions work with a session, an organization-wide API token or an agent token, like the other incident endpoints. Reading needs access to the incident; writing needs membership of the incident's team or the `admin` role (`403 imTeamMembershipRequired`). Creating or changing causes and reopening a completed postmortem need a session of an organization admin or a [reporting officer](/api/incident-management/nis2-settings) (`403 nis2OfficerRequired`). Postmortems of deleted incidents are only visible to them as well. An incident, postmortem or cause of another organization answers `404`, the same as a missing one. ## Causes The catalog is shared by every postmortem of your organization. Reading works with a session or a token; creating and changing causes needs a **signed-in session** of an organization admin or a reporting officer. API and agent tokens get `403 nis2OfficerRequired` there, so the requests below run from the dashboard session and are shown without a token. `GET /api/im/causes` answers `{ items, total, page, perPage }`, sorted by name. | Query | Description | |-------|-------------| | `includeArchived` | `true` or `1` also lists archived causes. Default `false`. | | `page` | Default `1`. | | `perPage` | Default `50`, at most `200`. | `POST /api/im/causes` creates a cause and answers `201` with it. | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | string | Yes | 1 to 200 characters, unique per organization regardless of case (`409 causeNameTaken`). | | `description` | string or null | No | At most 2000 characters. | `PATCH /api/im/causes/:id` changes `name`, `description` or `archived` (`true` archives, `false` restores) and answers the cause. A cause of another organization or an unknown one answers `404 causeNotFound`, a name already in use `409 causeNameTaken`. Causes are never deleted: archived causes stay on old postmortems and still count for repeated incidents. ```http POST /api/im/causes Content-Type: application/json { "name": "Expired TLS certificate" } ``` `201 Created` ```json { "id": 3, "publicId": "0b7f1c52-6a0e-4c4f-9d1e-2f7c9a3b8e11", "name": "Expired TLS certificate", "description": null, "archivedAt": null, "createdAt": "2026-10-22T09:00:00.000Z", "updatedAt": "2026-10-22T09:00:00.000Z" } ``` | Field | Description | |-------|-------------| | `archivedAt` | `null` while active. Archived causes are hidden from the picker, stay on old postmortems and still count for repeated incidents. | ## Postmortem of an incident `GET /…
### Report Cases (NIS-2)
URL: https://docs.uptimeify.io/api/incident-management/report-cases
Description: Track an NIS-2 report case: criteria, the reportable decision, awareness time, deadlines, report drafts and the log of what you submitted in the BSI portal.
Summary: `GET /api/im/report-cases` · `POST /api/im/report-cases` · `GET /api/im/report-cases/:id` · `PATCH /api/im/report-cases/:id` `POST /api/im/report-cases/:id/aware-at` · `POST /api/im/report-cases/:id/criteria` · `POST /api/im/report-cases/:id/decision` · `POST /api/im/report-cases/:id/interim-request` · `POST /api/im/report-cases/:id/close` `POST /api/im/report-cases/:id/incidents` · `DELETE /api/im/report-cases/:id/incidents/:incidentId` · `GET /api/im/report-cases/:id/draft` · `POST /api/im/report-cases/:id/submissions` A report case collects what you need for an NIS-2 report (Art. 23 NIS-2 Directive, § 32 BSIG): the linked incidents, a decision per significance criterion, the decision whether the incident is reportable, the time you became aware, and the deadlines that follow (early warning 24 h, notification 72 h, final report one month after the notification, intermediate report on request). **You submit every report yourself in the BSI portal. Uptimeify transmits nothing and never classifies an incident on its own.** Criteria, submissions and the timeline are append-only: nothing can be changed or deleted afterwards. Closed cases are kept for three years. `:id` is the case's `publicId` or its numeric `id`. `:incidentId` is the numeric ID of an IM incident. ## Authentication Session only (dashboard login); API tokens are rejected with `403` (`nis2OfficerRequired`). NIS-2 report cases must be switched on ([NIS-2 Settings](/api/incident-management/nis2-settings)). Organization admins and the listed reporting officers can read and write; everyone else gets `403`. A case of another organization answers `404` (`reportCaseNotFound`), the same as a missing one. ## List report cases `GET /api/im/report-cases` | Query | Description | |-------|-------------| | `status` | Comma-separated status filter, e.g. `reportable,early_warning_submitted`. | | `page` | Default `1`. | | `perPage` | Default `50`, at most `200`. | Sorted by the next open deadline; cases without one come last, newest first. ```bash curl "$BASE_URL/api/im/report-cases?status=reportable&perPage=20" -H "Cookie: $SESSION_COOKIE" ``` `200 OK` ```json { "items": [ { "id": 12, "publicId": "0b6f9a52-7a43-4c8e-9f1e-5c2d8a1b3e77", "title": "Outage customer portal", "status": "reportable", "awareAt": "2026-10-21T07:00:00.000Z", "createdAt": "2026-10-21T07:05:00.000Z", "nextDeadline": { "stage": "early_warning", "dueAt": "2026-10-22T07:00:00.000Z", "met": false, "metAt": null, "late": false }, "lateStages": [], "incidentCount": 1 } ], "total": 1, "page": 1, "perPage": 20 } ``` `nextDeadline` is the earliest unmet deadline (see [deadline fields](#get-a-report-case)) or `null`. `lateStages` lists the stages whose deadline was met late, also on closed cases. Status values: `assessment`, `not_reportable`, `reportable`, `early_warning_submitted`, `notification_submitted`, `final_submitted`, `closed`. ## Open a report case `POST /api/im/report-cases` | Field | Type | Required | Description | |-------|------|----------|-------------| | `title` | string | Yes | 1 to 200 characters. | | `incidentIds` | integer[] | No | IM incidents of your organization, at most 50, no test incidents. | `awareAt` starts at the time of the request; correct it with `aware-at`. Any other key is a `400`. ```bash curl -X POST "$BASE_URL/api/im/report-cases" -H "Cookie: $SESSION_COOKIE" -H "Content-Type: application/json" \ -d '{ "title": "Outage customer portal", "incidentIds": [4812] }' ``` `201 Created`: the full case, same shape as [Get a report case](#get-a-report-case). ## Get a report case `GET /api/im/report-cases/:id` `200 OK` ```json { "id": 12, "publicId": "0b6f9a52-7a43-4c8e-9f1e-5c2d8a1b3e77", "organizationId": 2, "title": "Outage customer portal", "status": "reportable", "awareAt": "2026-10-21T07:00:00.000Z", "decision": "reportable", "decidedBy": "u_8f2c", "decidedAt": "2026-10-21T08:10:00.000Z", "decisionReason": null, "suspectedMalicious": true, "crossBorder": false, "severityAssessment": "hig…
### Reports
URL: https://docs.uptimeify.io/api/incident-management/reports
Description: Incident report (volume, MTTA, MTTR by team, severity, category or month) and on-call report (minutes per user) for a date range, as JSON or CSV, and the NIS-2 management report as JSON or PDF.
Summary: Two reports over an explicit date range, each available as JSON or as a CSV download, and the [NIS-2 management report](#nis-2-management-report) as JSON or PDF. ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token. Incident Management must be enabled for the organization. ## Date range Both reports require `from` and `to` as ISO 8601. `from` is inclusive, `to` exclusive, `to` must be after `from`, and the range may span at most 400 days. ## Incident report `GET /api/im/reports/incidents` Counts the incidents triggered in the range and their mean time to acknowledge (MTTA) and to resolve (MTTR), in minutes. An incident that was never acknowledged or resolved is left out of that average, it does not count as zero. Test incidents are excluded. ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `from`, `to` | ISO 8601 | Yes | See [Date range](#date-range). | | `groupBy` | string | No | `month` (default), `team`, `severity`, `category` or `service`. With `service`, `groupKey` is the [service](/api/incident-management/services) ID and incidents without a service form the group `none`. Any other value is rejected with `400`. | | `tz` | number | No | Your UTC offset in minutes (e.g. `120`), default `0`, clamped to plus or minus 1440. Decides which local month an incident belongs to. Not an integer: `400`. | | `format` | string | No | `json` (default) or `csv`, which returns a CSV file instead of JSON. Any other value: `400`. | ### Example (cURL) ```bash curl "$BASE_URL/api/im/reports/incidents?from=2026-07-01T00:00:00Z&to=2026-10-01T00:00:00Z&groupBy=severity" \ -H "Authorization: Bearer $TOKEN" ``` ### Response ```json { "from": "2026-07-01T00:00:00.000Z", "to": "2026-10-01T00:00:00.000Z", "groupBy": "severity", "summary": { "count": 27, "mttaMinutes": 6.4, "mttrMinutes": 82.15 }, "groups": [ { "groupKey": "sev1", "groupLabel": "sev1", "count": 3, "mttaMinutes": 1.8, "mttrMinutes": 41.5 }, { "groupKey": "sev3", "groupLabel": "sev3", "count": 24, "mttaMinutes": 7.1, "mttrMinutes": 87.24 } ] } ``` `groupKey` / `groupLabel` per grouping: `team` gives the team ID and team name, `severity` gives `sev1` to `sev4`, `category` gives `availability`, `security`, `other` or `uncategorized` (not classified yet), `month` gives the UTC instant of the local month start (e.g. `2026-08-31T22:00:00.000Z` for August with `tz=120`) in both fields. Groups without incidents are omitted. Averages are rounded to two decimals and `null` when no incident in the group qualifies. With `format=csv` the response is `text/csv` with `Content-Disposition: attachment; filename="incidents-report-.csv"` and the columns `,count,mttaMinutes,mttrMinutes`. Month labels are written as `YYYY-MM`, empty averages as empty cells. The summary is not part of the CSV. ## On-call report `GET /api/im/reports/on-call` On-call minutes per user inside the range. Shifts that start before `from` or end after `to` only count their part inside the range. Team-level overrides of type `online` (without a schedule) are added on top of the scheduled shifts. ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `from`, `to` | ISO 8601 | Yes | See [Date range](#date-range). | | `format` | string | No | `json` (default) or `csv`, which returns a CSV file instead of JSON. Any other value: `400`. | ### Example (cURL) ```bash curl "$BASE_URL/api/im/reports/on-call?from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z" \ -H "Authorization: Bearer $TOKEN" ``` ### Response ```json { "periodStart": "2026-09-01T00:00:00.000Z", "periodEnd": "2026-10-01T00:00:00.000Z", "users": [ { "userId": "u_abc123", "userName": "Jana Weber", "minutes": 21600 }, { "userId": "u_def456", "userName": "Tobias Brandt", "minutes": 21600 } ] } ``` `users` is sorted by `userId`, `minutes` rounded to two decimals. Users without on-call time i…
### Resolve Incident
URL: https://docs.uptimeify.io/api/incident-management/resolve-incident
Description: Resolves an Incident Management incident from any non-closed status. This is the only endpoint that can move an incident to resolved.
Summary: `POST /api/im/incidents/:id/resolve` Resolves an incident from any non-closed status (`triggered`, `acknowledged`, `investigating`, `identified`, `monitoring`). This is the only endpoint that can move an incident to `resolved`; [Change status](/api/incident-management/acknowledge-incident#change-status) deliberately rejects `resolved` as a target. Resolving stops escalation, sends the resolve notices to the people who were paged, updates status pages driven by a [status page rule](/api/incident-management/statuspage-rules) and notifies outbound integrations. For a test incident (`isTest: true`) the notices, status page update and outbound notification are skipped. ## Authentication Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token, see [Authentication](/api/incident-management#authentication). Incident Management must be enabled for the organization. Restricted to the incident's team: you must be a member of the incident's team (`teamId`) or an organization admin. An organization-wide API token passes as an organization admin. [Acknowledging](/api/incident-management/acknowledge-incident#acknowledge) is not restricted this way. ## Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `note` | string | No | `null` | Optional free-text resolution note, up to 10,000 characters. | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/incidents/42/resolve" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "note": "Restarted the connection pool, monitoring for recurrence." }' ``` ## Response `200 OK`: the updated incident row (same shape as the `items` of [List Incidents](/api/incident-management/list-incidents), without the enrichment fields). ```json { "id": 42, "organizationId": 1, "teamId": 3, "title": "Database connection pool exhausted", "customerId": null, "primarySourceId": 7, "severity": "sev1", "severityManual": false, "status": "resolved", "mergedIntoId": null, "escalationPolicyId": null, "currentTier": null, "escalationEpoch": 2, "escalationCycle": 0, "acknowledgedBy": "MFcTjWmYq2LpzR8vK1sXo", "acknowledgedAt": "2026-07-17T09:20:00.000Z", "snoozedUntil": null, "autoResolve": true, "resolvedBy": null, "resolveNote": "Restarted the connection pool, monitoring for recurrence.", "statuspageUpdate": null, "createdBy": null, "sourceKind": "alert", "isTest": false, "triggeredAt": "2026-07-17T09:12:00.000Z", "resolvedAt": "2026-07-17T09:45:00.000Z" } ``` ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the session user has no IM-eligible role - `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization - `403 Forbidden` (`imTeamMembershipRequired`) when you are neither a member of the incident's team nor an organization admin - `400 Bad Request` (`invalidRequestBody`) when `:id` is not a positive integer, or `note` is not a string or exceeds 10,000 characters - `404 Not Found` (`imIncidentNotFound`) when the incident does not exist, or belongs to another organization - `422 Unprocessable Entity` (`imIncidentAlreadyClosed`) when the incident is already `resolved` or `merged` - `409 Conflict` (`imIncidentStatusConflict`) when the incident was closed concurrently between the read and the write
### Routing Rules
URL: https://docs.uptimeify.io/api/incident-management/routing-rules
Description: List, create, update and delete Incident Management routing rules: which team a new incident is assigned to, and an optional severity override.
Summary: `GET /api/im/routing` · `POST /api/im/routing` · `GET /api/im/routing/:id` · `PATCH /api/im/routing/:id` · `DELETE /api/im/routing/:id` A **routing rule** decides which [team](/api/incident-management/teams) a new incident belongs to. When an alert opens an incident, the rules of your organization are walked in order of `priority` (lowest first, `id` as tiebreak). The first rule whose `match` applies wins: the incident goes to that rule's `teamId`, and `severityOverride` (if set) replaces the alert's severity. If no rule matches, the incident goes to the team of the [alert source](/api/incident-management/alert-sources) that received the alert. ## Authentication Requires the base IM access every endpoint in this API needs (an IM-eligible role `admin`, `editor` or `responder`, or an organization-wide API token; Incident Management must be enabled for the organization). Reading is open to any IM-eligible role. **Creating, updating and deleting** additionally require the write bar: your role must be `admin`, or you must be a team admin of the rule's team. An organization-wide API token runs with the role of the user who created it, so a token created by an organization admin passes this bar. Team-admin membership never applies to a token. ## The `match` object | Field | Type | Description | |-------|------|-------------| | `sourceIds` | integer[] | Alert source IDs. Max 500 entries. | | `severity` | string[] | Alert severities, each one of `sev1`, `sev2`, `sev3`, `sev4`. | | `customerIds` | integer[] | Customer IDs. Max 500 entries. | | `monitorIds` | integer[] | Monitor IDs. Max 500 entries. | | `tags` | string[] | Non-empty strings. Max 200 entries. | | `fieldMatches` | object | String values only. Max 50 keys. | An empty object `{}` (or omitting `match`) matches every alert, which makes a catch-all rule at a high `priority` number. Every ID in `sourceIds`, `customerIds` and `monitorIds` must belong to your organization, otherwise the request fails with `422`. All set fields must match (AND); an empty array or an empty `fieldMatches` constrains nothing. **Deprecated fields:** until 2027-01-18 responses still carry `match.source_ids`, `match.customer_ids`, `match.monitor_ids` and `match.field_matches` next to their successors, and request bodies still accept them. Send the camelCase names; both spellings with different values answer `400` `invalidRequestBody`. - `customerIds` and `monitorIds` match alerts from the built-in monitoring bridge, which carry the monitor's customer and id. Alerts from other sources have neither, so a rule that sets these fields never matches them. - `tags` matches when the alert's mapped `tags` (attribute mapping) share at least one value, ignoring case. - `fieldMatches` compares each key, as text, with the mapped field of that name, or else the top-level payload field of that name. A missing field does not match. ## List routing rules `GET /api/im/routing` Returns all rules of your organization, in evaluation order (`priority` ascending, then `id` ascending). ### Query Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `envelope` | string | none | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/routing?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ### Response `200 OK` ```json { "items": [ { "id": 4, "organizationId": 1, "priority": 10, "match": { "sourceIds": [7], "severity": ["sev1", "sev2"] }, "teamId": 3, "escalationPolicyId": null, "severityOverride": "sev1", "createdAt": "2026-09-14T08:00:00.000Z", "updatedAt": "2026-09-14T08:00:00.000Z" }, { "id": 5, "organizationId": 1, "priority": 100, "match": {}, "teamId": 2, "escalationPolicyId": null, "severityOverride": null, "createdAt": "2026-09-14T08:05:00.000Z", "updatedAt": "2026-09-14T08:05:00.000Z" } ], "total": 2, "page": 1, "perPage": 2 } ``` **List form…
### Schedule Overrides
URL: https://docs.uptimeify.io/api/incident-management/schedule-overrides
Description: List, add, edit and delete on-call overrides on a schedule: one-off windows that put someone on call or take someone off call without touching the rotation.
Summary: An **override** is a one-off window on top of a [schedule](/api/incident-management/schedules)'s regular rotation, for a holiday swap or a sick day, without editing the rotation itself. This page covers overrides attached to one schedule. Overrides that belong to the team without a schedule are on [Team Overrides](/api/incident-management/team-overrides). ## Authentication Base IM access: an IM-eligible role or an organization-wide API token, and Incident Management activated for the organization. Listing is open to any caller with that access. Adding, editing and deleting need the team write bar for the schedule's team: organization `admin` role, or team admin. An API token runs with the role of the user who created it, so only a token created by an organization admin passes. **Exception: giving away your own shift.** A plain member of the schedule's team may add one kind of override without the write bar, and delete it again: - `userId` is the caller, `type` is `offline`, `applyScope` is `this_team` (or omitted), `escalationTierOrder` is `null` (or omitted), - `coveredByUserIds` holds exactly one user, not the caller, who is a member of the schedule's team, - the window has not ended yet, is at most 7 days long, and from `startsAt` (or now, if later) to `endsAt` lies inside one contiguous stretch of the caller's own on-call shifts on this schedule (back-to-back shifts count as one stretch), - no `offline` override of the caller on this schedule overlaps the window yet. The coverer is put on call exactly for that window. This includes duty an admin put the caller on with an `online` override: `offline` overrides apply after `online` ones, so the member can give that duty away too. The coverer receives an email (the on-call shift notice, unless they turned off email or handoff notices in their notification settings), and another one when the override is deleted again, by the caller or by an admin; an identical repeat (same kind, overlapping window) within 10 minutes is sent once, a change between given and taken back is always sent. Whenever someone takes themselves offline with coverers (a member or an admin), every coverer gets this notice, and every coverer gets the "taken back" notice when the override is deleted. A member can give away at most 10 shifts per hour; the 11th gets `429` `imShiftGiveAwayRateLimited`. A member may delete only an `offline` override about themselves that they created themselves; an override an admin created about them stays admin-only. Editing stays admin-only. Anything else a member sends is refused with `403` `imShiftGiveAwayDenied` and a `reason` (see [Common errors](#common-errors)). ## Override fields | Field | Type | Required | Description | |-------|------|----------|-------------| | `userId` | string | Yes | The subject: the user who goes on call (`online`) or off call (`offline`). | | `startsAt` | string | Yes | ISO 8601 timestamp, window start. | | `endsAt` | string | Yes | ISO 8601 timestamp, window end. Must be after `startsAt`. | | `type` | string | Yes | `online`: the subject is on call for the window and replaces everyone else on call. `offline`: the subject is taken off call. | | `coveredByUserIds` | string[] | No | `offline` only, up to 200: who takes over the pager. All listed coverers are paged, each one for exactly the pages the subject would get. Empty or omitted leaves a gap that the escalation engine fills from another tier when it pages. Must be empty for `online`. | | `applyScope` | string | No | `this_team` (default) or `all_teams`: also apply to every other team the subject is a member of. | | `escalationTierOrder` | integer \| null | No | Only apply on this tier (`tierOrder`, 1 or more). `null` or omitted = all tiers. | Every user id (subject and covers) must be an active user of your organization with the organization role `admin`, `editor` or `responder`. When two online overrides overlap, the one created later wins. There is no priority field, precedence is creation…
### Preview a schedule
URL: https://docs.uptimeify.io/api/incident-management/schedule-preview
Description: Compute the shifts and coverage gaps a schedule's saved rotation produces over the next four weeks, without writing anything.
Summary: `POST /api/im/schedules/:id/preview` Runs the schedule's **saved** configuration (cadence, rotation groups, weekly windows, validity range) through the same shift calculation the paging worker uses, for the next four weeks from now, and returns the shifts and the gaps where nobody is on call. Nothing is stored. By default the schedule's own saved overrides are included. Send `overrides` to try other override windows instead. Team-level overrides and `all_teams` overrides created on other schedules are not part of the preview. ## Authentication Base IM access: an IM-eligible role (`admin`, `editor` or `responder`) or an organization-wide API token, and Incident Management activated for the organization. No team role is needed. ## Request Body The body is optional. | Field | Type | Required | Description | |-------|------|----------|-------------| | `overrides` | array | No | Up to 500 override windows that replace the saved overrides for this preview. Each: `{ userId, startsAt, endsAt, type?, coveredByUserIds? }`, `type` `online` (default) or `offline`, `coveredByUserIds` only for `offline`. `[]` previews without any overrides. | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/schedules/7/preview" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ``` ## Response `200 OK` ```json { "from": "2026-10-09T12:00:00.000Z", "to": "2026-11-06T12:00:00.000Z", "timezone": "Europe/Berlin", "shifts": [ { "userId": "u_abc123", "layerIndex": 0, "startsAt": "2026-10-09T12:00:00.000Z", "endsAt": "2026-10-12T07:00:00.000Z", "isOverride": false }, { "userId": "u_def456", "layerIndex": 0, "startsAt": "2026-10-12T07:00:00.000Z", "endsAt": "2026-10-19T07:00:00.000Z", "isOverride": false } ], "gaps": [ { "from": "2026-11-02T07:00:00.000Z", "to": "2026-11-06T12:00:00.000Z" } ] } ``` - `layerIndex` numbers the concurrent on-call positions (`0` to `roundRobinSize - 1`); override shifts sit on higher indexes. `isOverride` is `true` for a shift that comes from an override. - `gaps` lists every stretch of the window in which no shift covers anyone. A schedule without rotation groups has one gap over the whole window. ## Common errors - `401 Unauthorized` (`unauthorized`) when not authenticated - `403 Forbidden` (`imAccessDenied`) for a customer-scoped token, or a session without an IM-eligible role - `403 Forbidden` (`imNotEnabled`) when Incident Management is not activated for the organization - `404 Not Found` (`imScheduleNotFound`) when `:id` does not exist or belongs to another organization - `400 Bad Request` (`invalidRequestBody`) when `:id` is not a positive integer, `overrides` is not an array or has more than 500 entries, an entry has no `userId` or no valid `startsAt` before `endsAt`, or the saved configuration cannot be turned into shifts (the message says why)
### Schedules
URL: https://docs.uptimeify.io/api/incident-management/schedules
Description: List, read, create and delete Incident Management on-call schedules, and how a schedule's rotation cadence works.
Summary: A **schedule** belongs to one team and one of its [escalation tiers](/api/incident-management/team-tiers). Its timezone, validity range, weekly windows, rotation cadence and rotation groups decide who is on shift when. A background worker turns that definition into concrete shifts up to 90 days ahead; paging, [Who Is On Call](/api/incident-management/on-call) and the [team calendar](/api/incident-management/team-insights#calendar) read those shifts. These endpoints manage the definition, not the shifts. Configure the rotation with [Update a schedule](/api/incident-management/update-schedule), or create a fully configured schedule in one call with [Add a schedule to a tier](/api/incident-management/team-tiers#add-a-schedule-to-a-tier). [Preview a schedule](/api/incident-management/schedule-preview) shows the resulting shifts. ## Authentication Base IM access: an IM-eligible role (`admin`, `editor` or `responder`) or an organization-wide API token, and Incident Management activated for the organization. Listing and reading are open to any caller with that access. Creating and deleting need the team write bar for the schedule's team: organization `admin` role, or team admin. An API token runs with the role of the user who created it, so only a token created by an organization admin passes. ## List schedules `GET /api/im/schedules` Returns every schedule of your organization, ordered by name. ### Query Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `envelope` | string | none | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/schedules?envelope=items" \ -H "Authorization: Bearer $TOKEN" ``` ### Response `200 OK` ```json { "items": [ { "id": 7, "organizationId": 1, "teamId": 3, "teamName": "Platform Team", "name": "Primary On-Call", "timezone": "Europe/Berlin", "tierId": 21, "createdAt": "2026-06-02T08:00:00.000Z", "updatedAt": "2026-09-14T10:12:00.000Z" } ], "total": 1, "page": 1, "perPage": 1 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form (a bare array of the same schedules), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. ## Get a schedule `GET /api/im/schedules/:id` Returns the full schedule configuration, its team and its overrides (same item shape as [Schedule Overrides](/api/incident-management/schedule-overrides)). `rotations` lists the rotation groups with their members (with `userImage`), in the same shape as `schedules[].rotations` of [Get a tier](/api/incident-management/team-tiers#get-a-tier); they are also part of the team's [escalation chain](/api/incident-management/team-tiers#read-the-escalation-chain). ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/schedules/7" \ -H "Authorization: Bearer $TOKEN" ``` ### Response `200 OK` ```json { "id": 7, "organizationId": 1, "teamId": 3, "tierId": 21, "name": "Primary On-Call", "timezone": "Europe/Berlin", "effectiveFrom": null, "effectiveUntil": null, "weeklySchedules": [], "rotationMode": "explicit", "rotationRepeats": "weekly", "customRepeatUnit": null, "customRepeatValue": null, "autoRotationSize": null, "roundRobinSize": 1, "roundRobinCursor": 4, "startsOnDayOfWeek": 1, "startsOnDateOfMonth": null, "startsOnTime": "09:00", "createdAt": "2026-06-02T08:00:00.000Z", "updatedAt": "2026-09-14T10:12:00.000Z", "team": { "id": 3, "name": "Platform Team" }, "overrides": [], "rotations": [ { "id": 31, "rotationOrder": 1, "members": [ { "userId": "usr_abc", "userName": "Alex Example", "userImage": null, "memberOrder": 1 } ] } ] } ``` `roundRobinCursor` is an internal counter for round-robin paging and cannot be set. ## Create a schedule `POST /api/im/schedules` Creates an empty schedule under a tier: 24/7, `rotationMode: "none"`, no rotation groups. It pages nobody until you add rotation groups…
### Services
URL: https://docs.uptimeify.io/api/incident-management/services
Description: List, create, update and delete the services of your organization (service and asset inventory with criticality and responsible team), and how incidents are assigned to them.
Summary: `GET /api/im/services` · `POST /api/im/services` · `GET /api/im/services/:id` · `PATCH /api/im/services/:id` · `DELETE /api/im/services/:id` A **service** is something your organization runs and that an incident can affect, for example "Web shop", "Customer portal" or "Mail". Each service has a **criticality** (`critical`, `high`, `medium`, `low`), an optional responsible [team](/api/incident-management/teams), and the monitors it consists of. This is the service and asset inventory NIS-2 asks for (Implementing Regulation (EU) 2024/2690, Annex 12 and 5.2). Every incident carries `serviceId` (`null` = no service). It is set in two ways: - **Automatically** when an incident is opened by the built-in monitoring bridge and its monitor belongs to **exactly one** service of your organization. A monitor in two services is ambiguous and leaves `serviceId` empty; alerts from any other source (webhooks, email, API) are never assigned automatically. - **By hand** with [Set Incident Service](/api/incident-management/incident-service). `:id` accepts the numeric `id` or the `publicId`. ## Authentication Reading is open to every IM-eligible role (`admin`, `editor`, `responder`) and to organization-wide API tokens, see [Authentication](/api/incident-management#authentication). **Creating, updating and deleting** require the organization `admin` role; an API token runs with the role of the user who created it. Other roles get `403` `imServiceWriteDenied`. ## The service object | Field | Type | Description | |-------|------|-------------| | `id` | integer | Internal ID. | | `publicId` | string (UUID) | Public ID. | | `organizationId` | integer | Owning organization. | | `name` | string | 1 to 200 characters, unique per organization regardless of case. | | `description` | string \| null | At most 2000 characters. | | `criticality` | string | `critical`, `high`, `medium` or `low`. | | `ownerTeamId` | integer \| null | Responsible team; becomes `null` when the team is deleted. | | `monitors` | object[] | `{ monitorType, monitorId, monitorName }`, sorted by name. A monitor that was deleted no longer appears. | | `createdAt` / `updatedAt` | string (ISO 8601) | | `monitorType` is one of `website` (also heartbeat and browser monitors), `dns`, `icmp`, `smtp`, `ssh`, `tcp`, `ftp`, `imap_pop`. Each type has its own IDs, so a monitor is always identified by the pair `monitorType` + `monitorId`. ## List services `GET /api/im/services` | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `page` | integer | `1` | Page number. | | `perPage` | integer | `50` | Page size, at most `200`. | ```bash curl "$BASE_URL/api/im/services" \ -H "Authorization: Bearer $TOKEN" ``` `200 OK`, sorted by name: ```json { "items": [ { "id": 4, "publicId": "0d7c6a0e-6f43-4d3b-9b1e-2a8f1d1c5e77", "organizationId": 1, "name": "Web shop", "description": "Storefront and checkout", "criticality": "critical", "ownerTeamId": 3, "monitors": [ { "monitorType": "website", "monitorId": 46, "monitorName": "shop.example.com" }, { "monitorType": "dns", "monitorId": 9, "monitorName": "example.com DNS" } ], "createdAt": "2026-10-25T08:00:00.000Z", "updatedAt": "2026-10-25T08:00:00.000Z" } ], "total": 1, "page": 1, "perPage": 50 } ``` ## Get a service `GET /api/im/services/:id` returns one service in the same shape. ## Create a service `POST /api/im/services` | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | string | Yes | 1 to 200 characters, unique per organization regardless of case (`409 imServiceNameTaken`). | | `description` | string \| null | No | At most 2000 characters. | | `criticality` | string | No | `critical`, `high`, `medium` (default) or `low`. | | `ownerTeamId` | integer \| null | No | A team of your organization (`404 imTeamNotFound`). | | `monitors` | object[] | No | `{ monitorType, monitorId }`, at most 500. Every monitor must belong to your organization (`404 imServiceMonitorNotFound`, `data.mo…
### Setup Progress and Test Page
URL: https://docs.uptimeify.io/api/incident-management/setup
Description: Read and store the progress of the Incident Management setup, and send yourself a test page through a team.
Summary: `GET /api/im/setup/state` · `PATCH /api/im/setup/state` · `POST /api/im/setup/test-page` The organization keeps one free-form setup object, so a setup flow (team, schedule, alert source, test page) can be resumed on another device or by another admin. These endpoints read and write that object, and send a test page to check that paging reaches you. ## Authentication All three need an IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token. - The **setup state** is reachable before Incident Management is [activated](/api/incident-management/activate). Writing it requires the `admin` role of the organization. - The **test page** requires Incident Management to be enabled and write access to the team: the `admin` role, or team-admin membership. It pages **you**, so it needs a user session; an organization-wide API token receives `403` (`imAccessDenied`). ## Get the setup state `GET /api/im/setup/state` ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/setup/state" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ### Response ```json { "organizationId": 42, "setupState": { "teamId": 7, "sourceCreated": true } } ``` `setupState` is whatever was last stored (the keys above are only an example). It is `{}` until something was stored. ## Store the setup state `PATCH /api/im/setup/state` Replaces the stored object as a whole. ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `setupState` | object | Yes | A plain JSON object, at most 8 KB serialized. | ### Example (cURL) ```bash curl -X PATCH "$BASE_URL/api/im/setup/state" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"setupState":{"teamId":7,"sourceCreated":true}}' ``` ### Response The stored state, in the same shape as the GET. ## Send a test page `POST /api/im/setup/test-page` Creates a test incident (`isTest: true`, severity `sev4`, title "Setup wizard test page") in the given team and pages the caller on every channel that can reach them: - `email`, always - `sms`, when a verified phone number is set in the [notification settings](/api/incident-management/notification-settings) - `voice`, additionally when `includeVoice` is `true` and the phone number is verified Test incidents are not counted by [Count Open Incidents](/api/incident-management/incident-count). Test pages and [test notifications](/api/incident-management/notification-settings#send-a-test-notification) share one limit of 5 per hour per user. ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `teamId` | number | Yes | A team of your organization. | | `includeVoice` | boolean | No | Also place a voice call. Default `false`. | ### Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/setup/test-page" \ -H "Content-Type: application/json" \ -b "$SESSION_COOKIE" \ -d '{"teamId":7}' ``` ### Response ```json { "incidentId": 1834, "channels": ["email", "sms"], "enqueueErrors": [] } ``` `enqueueErrors` lists the channels whose page could not be queued. Empty on success. ## Common errors - `400 Bad Request` (`invalidRequestBody`) when `setupState` is missing, not an object or larger than 8 KB, or when `teamId` is missing or not an integer, or `includeVoice` is not a boolean - `401 Unauthorized` when not authenticated - `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token - `403 Forbidden` (`imAccessDenied`) when the caller has no IM-eligible role, or when the test page is requested with an API token - `403 Forbidden` (`forbidden`) when a non-admin writes the setup state - `403 Forbidden` (`imNotEnabled`) when sending a test page before Incident Management is enabled - `403 Forbidden` (`imTeamWriteDenied`) when the caller may not write the team - `422 Unprocessable Entity` (`invalidTeamId`) when the team does not exist in your organization - `429 Too Many Requests` (`imTestNotificationRateLimited`) afte…
### Status Page Rules
URL: https://docs.uptimeify.io/api/incident-management/statuspage-rules
Description: Couple Incident Management to your status pages: rules that flip a page to warning or degraded on incidents of a team, plus a manual override.
Summary: `GET /api/im/statuspage-rules` · `POST /api/im/statuspage-rules` · `GET /api/im/statuspage-rules/:id` · `PATCH /api/im/statuspage-rules/:id` · `DELETE /api/im/statuspage-rules/:id` · `GET /api/im/statuspage-rules/override` · `POST /api/im/statuspage-rules/override` · `DELETE /api/im/statuspage-rules/override/:statusPageId` A **status page rule** reads: "incidents of team X at severity `minSeverity` or worse set status page Y to `targetState`". `sev1` is the most severe. The page shows the incident's status page update as its text, or the rule's `message` while the incident has none. With `autoResolve`, the page state is reset when the incident resolves. A **manual override** pins a state on a status page by hand. While a manual override is active, rules neither change nor clear that page. ## Authentication Requires the base IM access every endpoint in this API needs (an IM-eligible role `admin`, `editor` or `responder`, or an organization-wide API token; Incident Management must be enabled for the organization). Listing and reading rules is open to any IM-eligible role. - **Creating, updating and deleting rules** require the write bar: your role must be `admin`, or you must be a team admin of the rule's team. - **Setting or clearing a manual override** requires the `admin` or `editor` role, the same bar as other status page changes. An organization-wide API token runs with the role of the user who created it. Team-admin membership never applies to a token. ## List rules `GET /api/im/statuspage-rules` Returns all rules of your organization, ordered by `id`. ### Query Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `envelope` | string | none | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/statuspage-rules?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ### Response `200 OK` ```json { "items": [ { "id": 2, "organizationId": 1, "teamId": 3, "statusPageId": 15, "minSeverity": "sev2", "targetState": "degraded", "autoResolve": true, "componentIds": [8], "message": "We are currently investigating an issue.", "createdAt": "2026-09-25T09:00:00.000Z", "updatedAt": "2026-09-25T09:00:00.000Z" } ], "total": 1, "page": 1, "perPage": 1 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form (a bare array of the same rules), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. ## Get a rule `GET /api/im/statuspage-rules/:id` Reads one rule back, in the same shape as an entry of [List rules](#list-rules). Any IM-eligible role may call it. ### Example (cURL) ```bash curl "$BASE_URL/api/im/statuspage-rules/4" \ -H "Authorization: Bearer $TOKEN" ``` ### Response `200 OK`, one rule object as in the list above. `404` with `imStatuspageRuleNotFound` when the rule does not exist or belongs to another organization. ## Create a rule `POST /api/im/statuspage-rules` ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `teamId` | integer | Yes | Team of your organization whose incidents trigger the rule. You need the write bar on it. | | `statusPageId` | integer | Yes | Status page of your organization. | | `minSeverity` | string | No | `sev1` to `sev4`, default `sev2`. | | `targetState` | string | No | `warning` or `degraded` (default). | | `autoResolve` | boolean | No | Reset the page state when the incident resolves. Default `true`. Also accepts the strings `"true"`/`"false"`. | | `componentIds` | array or null | No | Components of `statusPageId` (id or publicId) the incident affects. While the incident is open, these manual components take `targetState` on the public page and the incident lists them as affected. `null` or empty: none. A component of another page answers `400 statusPageComponentN…
### Team On-Call and Statistics
URL: https://docs.uptimeify.io/api/incident-management/team-insights
Description: Read who is on call for a team right now, the team's on-call calendar for a time window, and the team's incident statistics.
Summary: Read-only views of one team: the current on-call set per tier, the on-call calendar, and incident statistics. For the organization-wide on-call view see [Who Is On Call](/api/incident-management/on-call). ## Authentication Base IM access: an IM-eligible role (`admin`, `editor` or `responder`) or an organization-wide API token, and Incident Management activated for the organization. No team role is needed. A team of another organization answers `404`. ## On-call now `GET /api/im/teams/:id/on-call-now` One entry per escalation tier, in tier order, with everyone on call in that tier right now. Overrides are already applied. A tier with nobody on call (no schedule, or a gap) has an empty `users` array. `uncoveredSince` (ISO 8601 or `null`) is when the last coverage of an empty tier ended, overrides included. It is `null` for a covered tier and for one nobody covered at any point in the last 14 days. Each entry of `users` carries `shiftEndsAt` and `shiftEndsAtIsLowerBound`: the end of that person's uninterrupted duty in this tier, with exactly the same meaning and the same value as in [`GET /api/im/on-call`](/api/incident-management/on-call). `shiftEndsAtIsLowerBound` is `true` when the duty does not end within the next 90 days; `shiftEndsAt` is then only "at least until". ### Query Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `envelope` | string | none | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/teams/3/on-call-now?envelope=items" \ -H "Authorization: Bearer $TOKEN" ``` ### Response `200 OK` ```json { "items": [ { "tierId": 21, "tierOrder": 1, "users": [{ "userId": "u_abc123", "userName": "Ada Lovelace", "userImage": null, "shiftEndsAt": "2026-10-17T07:00:00.000Z", "shiftEndsAtIsLowerBound": false }], "uncoveredSince": null }, { "tierId": 22, "tierOrder": 2, "users": [], "uncoveredSince": "2026-10-10T06:00:00.000Z" } ], "total": 2, "page": 1, "perPage": 2 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form (a bare array of the same entries), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. ## Calendar `GET /api/im/teams/:id/calendar` On-call spans of all tiers in a time window, as a flat list ordered by start. Overrides are already applied, team-level ones and schedule overrides limited to an escalation tier alike, by the same rules paging uses. ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `from` | string | Yes | ISO 8601 timestamp, window start (inclusive). | | `to` | string | Yes | ISO 8601 timestamp, window end (exclusive). Must be after `from`. | | `tier` | integer | No | A tier id of this team: only that tier's spans. An id that is not one of the team's tiers returns an empty list. | | `envelope` | string | No | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/teams/3/calendar?from=2026-10-01T00:00:00Z&to=2026-11-01T00:00:00Z&envelope=items" \ -H "Authorization: Bearer $TOKEN" ``` ### Response `200 OK` ```json { "items": [ { "scheduleId": 7, "tierOrder": 1, "userId": "u_abc123", "userName": "Ada Lovelace", "startsAt": "2026-09-28T07:00:00.000Z", "endsAt": "2026-10-05T07:00:00.000Z", "userImage": null }, { "scheduleId": null, "tierOrder": 1, "userId": "u_def456", "userName": "Bob Fixit", "startsAt": "2026-10-10T18:00:00.000Z", "endsAt": "2026-10-12T08:00:00.000Z", "userImage": null, "isTeamOverride": true } ], "total": 2, "page": 1, "perPage": 2 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form (a bare array of the same spans), which is deprecated; `{ items, ... }` becomes the…
### Team Members
URL: https://docs.uptimeify.io/api/incident-management/team-members
Description: Add, invite, re-role and remove the members of an Incident Management team.
Summary: Team membership decides who can be put on a team's rotations and overrides, and who is a **team admin** (`imRole: "admin"`) with write access to that one team. To read the current members, use [Get a team](/api/incident-management/teams#get-a-team). Member roles (`imRole`): `admin`, `member` or `stakeholder`. Default is `member`. Only accounts that could use Incident Management themselves can be members: active users with the organization role `admin`, `editor` or `responder`. ## Authentication Base IM access (an IM-eligible role or an organization-wide API token, Incident Management activated) plus the team write bar: organization `admin` role, or team admin of this team. An API token runs with the role of the user who created it, so only a token created by an organization admin passes. Creating a **new** user account through the invite additionally needs the organization `admin` role. ## Get a member `GET /api/im/teams/:id/members/:memberId` Reads one membership back, in the same shape as an entry of `members` in [Get a team](/api/incident-management/teams#get-a-team) (same masking: `user.email` is `null` and `user.phone` shows only the last four digits unless you are an organization admin). `user.phoneVerified` and `user.notificationRules` (readiness flags per urgency) are explained there too. Any IM-eligible role may call it. ### Example (cURL) ```bash curl "$BASE_URL/api/im/teams/3/members/18" \ -H "Authorization: Bearer $TOKEN" ``` ### Response `200 OK` ```json { "id": 18, "userId": "u_def456", "imRole": "member", "user": { "name": "Bob Fixit", "email": "bob@example.com", "image": null, "phone": "+4915112345678", "activeChannels": ["email", "push"], "phoneVerified": false, "notificationRules": { "high": { "hasPushRule": true, "hasSmsRule": false, "hasVoiceRule": false, "hasEmailRule": true }, "low": { "hasPushRule": false, "hasSmsRule": false, "hasVoiceRule": false, "hasEmailRule": true } } } } ``` `404` with `imTeamMemberNotFound` when `:memberId` is not a membership of this team. ## Add a member `POST /api/im/teams/:id/members` Adds an existing user of your organization to the team. ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `userId` | string | Yes | The user to add. Must belong to the team's organization. | | `imRole` | string | No | `admin`, `member` or `stakeholder`. Default `member`. | ### Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/teams/3/members" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "userId": "u_def456", "imRole": "member" }' ``` ### Response `200 OK` ```json { "id": 18, "userId": "u_def456", "imRole": "member", "user": { "name": "Bob Fixit", "email": "bob@example.com" } } ``` `id` is the membership id used by the endpoints below. `user.email` is `null` unless you are an organization admin. ## Invite a member by email `POST /api/im/teams/:id/invite` Adds a member by email address instead of user id: - **Email belongs to a user of your organization:** that user is linked to the team. Their account and role stay untouched, no email is sent. - **Email belongs to no account:** a new user with the organization role `responder` is created, linked to the team and sent an invitation email. Needs the organization `admin` role. - **Email belongs to an account in another organization:** refused with `422`, nothing is created. The email is matched case-insensitively and stored lowercase. ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `email` | string | Yes | Email address of the person to add. | | `imRole` | string | No | `admin`, `member` or `stakeholder`. Default `member`. | ### Example (cURL) ```bash curl -X POST "$BASE_URL/api/im/teams/3/invite" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "carla@example.com" }' ``` ### Response `200 OK` ```json { "id": 19, "userId": "u_ghi789", "imRole": "member", "invited…
### Team Overrides
URL: https://docs.uptimeify.io/api/incident-management/team-overrides
Description: List, add, edit and delete the on-call overrides of a team, both team-level overrides and those attached to one of the team's schedules.
Summary: These endpoints manage every override a team owns in one place: - **Team-level** overrides (`scheduleId: null`) need no schedule. They apply whenever the team's on-call set is resolved (paging, [on-call now](/api/incident-management/team-insights#on-call-now), the calendar), so a team can be driven by overrides alone. - **Schedule** overrides (`scheduleId` set) are the same overrides as on [Schedule Overrides](/api/incident-management/schedule-overrides), addressed through the team. The fields and their meaning (`type`, covers, scope, tier, precedence) are described under [Override fields](/api/incident-management/schedule-overrides#override-fields). This page adds one field: | Field | Type | Required | Description | |-------|------|----------|-------------| | `scheduleId` | integer \| null | No | A schedule of this team to attach the override to. Omitted or `null` = team-level. | An `offline` team-level override only removes the subject while they actually have a shift in that tier. For a subject who is not on call there, it has no effect. Team-level overrides are folded in after the union of the tier's schedules, with the same 1:1 substitution as schedule overrides: all coverers are paged in place of the covered person. They take effect the moment they are saved, including for the next page of an incident that is already open. The full order is under [How overrides are resolved](/api/incident-management/schedule-overrides#how-overrides-are-resolved). ## Authentication Base IM access: an IM-eligible role or an organization-wide API token, and Incident Management activated for the organization. Listing is open to any caller with that access. Adding, editing and deleting need the team write bar: organization `admin` role, or team admin of this team. An API token runs with the role of the user who created it, so only a token created by an organization admin passes. ## List overrides `GET /api/im/teams/:id/overrides` Returns all of the team's overrides, team-level and schedule-attached, ordered by `id`. ### Query Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `envelope` | string | none | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/teams/3/overrides?envelope=items" \ -H "Authorization: Bearer $TOKEN" ``` ### Response `200 OK`: same item shape as the schedule override list. ```json { "items": [ { "id": 31, "scheduleId": null, "userId": "u_def456", "userName": "Bob Fixit", "userImage": null, "type": "online", "applyScope": "this_team", "escalationTierOrder": 1, "startsAt": "2026-12-24T18:00:00.000Z", "endsAt": "2026-12-26T08:00:00.000Z", "createdAt": "2026-10-09T10:00:00.000Z", "coveredBy": [] } ], "total": 1, "page": 1, "perPage": 1 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form (a bare array of the same overrides), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. The list and the single `GET` return `coveredBy` as an array of objects (`userId`, `userName`, `userImage`); adding and editing return `coveredByUserIds` (user id strings) instead. ## Get an override `GET /api/im/teams/:id/overrides/:overrideId` Reads one override of this team back (team-level or schedule-scoped), in the same shape as an entry of [List overrides](#list-overrides). Any IM-eligible role may call it. ### Example (cURL) ```bash curl "$BASE_URL/api/im/teams/3/overrides/31" \ -H "Authorization: Bearer $TOKEN" ``` ### Response `200 OK`, one override object as in the list above. `404` with `imOverrideNotFound` when `:overrideId` is not an override of this team. ## Add an override `POST /api/im/teams/:id/overrides` ### Example (cURL) Bob takes tier 1 over Christmas: ```bash curl -X POST "$BASE_URL/api/im/teams/3/overrides" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: a…
### Escalation Tiers
URL: https://docs.uptimeify.io/api/incident-management/team-tiers
Description: Read, edit and test a team's escalation chain: ordered tiers, their auto-escalation and repeat settings, the schedules under each tier, and a dry run of who would be paged.
Summary: A team's escalation chain is an ordered list of **tiers**. Tier 1 is paged first; the people on call in a tier are whoever the tier's schedules have on shift right now. Each tier decides whether and when the incident moves on to the next tier, and how often the tier is paged again first. Whole-chain repeats live on the team ([Update a team](/api/incident-management/teams#update-a-team)). ## Authentication Base IM access: an IM-eligible role or an organization-wide API token, and Incident Management activated for the organization. Reading the chain is open to any caller with that access. Every write needs the team write bar: organization `admin` role, or team admin of this team. An API token runs with the role of the user who created it, so only a token created by an organization admin passes. ## Tier fields | Field | Type | Description | |-------|------|-------------| | `tierOrder` | integer | Position in the chain, 1 = paged first. Changed only through [Reorder](#reorder-tiers). | | `autoEscalationEnabled` | boolean | Whether the incident moves on to the next tier automatically. Default `true`. | | `autoEscalationAfterMinutes` | integer | Minutes before it moves on, `0` or more. Default `5`. | | `autoEscalationStopMode` | string | `acknowledged` or `resolved`: the incident state that stops the escalation. Default `acknowledged`. | | `autoEscalationSeverities` | array \| null | Severities that escalate automatically: a subset of `critical`, `warning`, `minor`. `null` = all. | | `autoEscalationTimeFilters` | array | Weekly windows in which auto-escalation may fire, up to 50, each `{ from: "HH:mm", until: "HH:mm", days: number[] }` with ISO weekdays (1 = Monday). `until` may be `"24:00"`. `[]` = always. | | `repeats` | integer | How many more times this tier is paged before moving on, `0` or more. Default `0`. | | `repeatsAfterMinutes` | integer \| null | Minutes between those repeats. `null` = use `autoEscalationAfterMinutes`. | | `repeatsStopMode` | string | `acknowledged` or `resolved`: the incident state that stops the repeats. Default `acknowledged`. | ## Read the escalation chain `GET /api/im/teams/:id/escalations` Returns all tiers in order, each with its schedules, rotation groups and members, plus the team's escalation settings. ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/teams/3/escalations" \ -H "Authorization: Bearer $TOKEN" ``` ### Response `200 OK` ```json { "tiers": [ { "id": 21, "tierOrder": 1, "autoEscalationEnabled": true, "autoEscalationAfterMinutes": 5, "autoEscalationStopMode": "acknowledged", "autoEscalationSeverities": null, "autoEscalationTimeFilters": [], "repeats": 0, "repeatsAfterMinutes": null, "repeatsStopMode": "acknowledged", "schedules": [ { "id": 7, "displayName": "Primary On-Call", "timezone": "Europe/Berlin", "effectiveFrom": null, "effectiveUntil": null, "weeklySchedules": [], "rotationMode": "explicit", "rotationRepeats": "weekly", "customRepeatUnit": null, "customRepeatValue": null, "autoRotationSize": null, "roundRobinSize": 1, "startsOnDayOfWeek": 1, "startsOnDateOfMonth": null, "startsOnTime": "09:00", "rotations": [ { "id": 12, "rotationOrder": 1, "members": [ { "userId": "u_abc123", "userName": "Ada Lovelace", "userImage": null, "memberOrder": 1 } ] } ] } ] } ], "teamSettings": { "timezone": "Europe/Berlin", "escalationRepeats": 1, "escalationRepeatsAfterMinutes": 15, "escalationRepeatsStopMode": "acknowledged", "engagementReportEnabled": false, "engagementReportDayOfWeek": null, "engagementReportTime": null } } ``` The schedule fields are explained under [Rotation cadence](/api/incident-management/schedules#rotation-cadence) and [Update a schedule](/api/incident-management/update-schedule). ## Get a tier `GET /api/im/teams/:id/tiers/:tierId` Reads one tier back with its schedules, rotations and members, in the same shape as an entry of `tiers` in [Read the escalation chain](#read-the-escalation-chain). Any IM-eligible role may call it. ### Example (cURL) ```bash curl "$BAS…
### Teams
URL: https://docs.uptimeify.io/api/incident-management/teams
Description: List, read, create, update and delete Incident Management teams, including the team-level escalation and engagement-report settings.
Summary: A **team** is the top-level ownership unit in Incident Management: escalation tiers, schedules, overrides and incidents all belong to exactly one team. This page covers the team itself. Members are on [Team Members](/api/incident-management/team-members), the escalation chain on [Escalation Tiers](/api/incident-management/team-tiers). ## Authentication Every endpoint needs base IM access: an IM-eligible role (`admin`, `editor` or `responder`) or an organization-wide API token, and Incident Management must be activated for the organization. Reads are open to any caller with that access. Writes need more: - **Create** needs the organization `admin` role. - **Update** and **delete** need the team write bar: organization `admin` role, or team admin (`imRole: "admin"`) of this team. An API token runs with the role of the user who created it. Only a token created by an organization admin passes either write bar. Teams of another organization always answer `404`, never `403`. ## List teams `GET /api/im/teams` Returns every team of your organization, ordered by name, with a member count and a short member list. ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/teams" \ -H "Authorization: Bearer $TOKEN" ``` ### Response `200 OK` ```json [ { "id": 3, "name": "Platform Team", "labelColor": "#4f46e5", "analyticsEnabled": true, "createdAt": "2026-06-02T08:00:00.000Z", "memberCount": 2, "members": [ { "userId": "u_abc123", "name": "Ada Lovelace", "email": "ada@example.com", "src": null }, { "userId": "u_def456", "name": "Bob Fixit", "email": "bob@example.com", "src": "https://uptimeify.io/avatars/u_def456.png" } ] } ] ``` `members[].email` is only filled for organization admins (and tokens created by one). Everyone else gets `null`, and a member without a display name then has an empty `name`. `src` is the member's avatar URL or `null`. ## Get a team `GET /api/im/teams/:id` Returns the team, its settings and its members with their notification readiness. ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/teams/3" \ -H "Authorization: Bearer $TOKEN" ``` ### Response `200 OK` ```json { "id": 3, "name": "Platform Team", "labelColor": "#4f46e5", "analyticsEnabled": true, "organizationId": 1, "createdAt": "2026-06-02T08:00:00.000Z", "updatedAt": "2026-09-14T10:12:00.000Z", "timezone": "Europe/Berlin", "escalationRepeats": 1, "escalationRepeatsAfterMinutes": 15, "escalationRepeatsStopMode": "acknowledged", "engagementReportEnabled": true, "engagementReportDayOfWeek": 1, "engagementReportTime": "09:00", "members": [ { "id": 17, "userId": "u_abc123", "imRole": "admin", "user": { "name": "Ada Lovelace", "email": "ada@example.com", "image": null, "phone": "+4915112345678", "activeChannels": ["email", "push", "sms"], "phoneVerified": true, "notificationRules": { "high": { "hasPushRule": true, "hasSmsRule": true, "hasVoiceRule": false, "hasEmailRule": true }, "low": { "hasPushRule": true, "hasSmsRule": false, "hasVoiceRule": false, "hasEmailRule": true } } } } ] } ``` - `members[].id` is the membership id that [Team Members](/api/incident-management/team-members) uses in its paths, not the user id. - `user.email` follows the same rule as in the list. `user.phone` is the verified phone number in full for organization admins, otherwise masked to the last four digits (`***5678`). - `user.activeChannels` lists the notification channels the member has switched on. - `user.phoneVerified` is `true` when the member has a confirmed phone number, so SMS and voice can reach them. - `user.notificationRules` says which channels the member's own rule chain uses: `high` for `sev1`/`sev2`, `low` for `sev3`/`sev4`, each with `hasPushRule`, `hasSmsRule`, `hasVoiceRule` and `hasEmailRule`. Only these flags are returned, never delays or numbers, so every IM role sees them; the phone masking above is unchanged. ## Create a team `POST /api/im/teams` ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | s…
### Update a schedule
URL: https://docs.uptimeify.io/api/incident-management/update-schedule
Description: Change an on-call schedule's name, timezone, validity range, weekly windows, rotation cadence and rotation membership, in one atomic call.
Summary: `PATCH /api/im/schedules/:id` This is where a schedule's rotation actually gets configured. [Creating a schedule](/api/incident-management/schedules) gives you an empty shell (`rotationMode: "none"`, no members); this endpoint sets the cadence, the weekly windows and who is in the rotation. Every field is **optional**. Only the fields present in the body are touched, a request body of `{ "name": "Primary" }` renames the schedule and changes nothing else. ## Authentication Requires base IM access (an IM-eligible role or an organization-wide API token, Incident Management activated for the organization) plus the team write bar: your role must be `admin`, or you must be a team admin of the schedule's team. An API token runs with the role of the user who created it, so only a token created by an organization admin passes. Customer logins (`readonly`), editors bound to a customer and customer-scoped tokens receive `403 imAccessDenied`. ## Request body | Field | Type | Description | |-------|------|-------------| | `name` | string | Schedule name, up to 120 characters. | | `timezone` | string | IANA timezone (e.g. `Europe/Berlin`). Every handover boundary and weekly window is evaluated in this zone, across DST. | | `effectiveFrom` | string \| null | ISO timestamp. The schedule pages nobody before it. `null` = no start bound. | | `effectiveUntil` | string \| null | ISO timestamp. The schedule pages nobody after it. `null` = no end bound. | | `weeklySchedules` | array | Recurring on-call windows, up to 50. Each: `{ from: "HH:mm", until: "HH:mm", days: number[] }`, `days` as ISO weekdays (1 = Monday .. 7 = Sunday). `until` may be `"24:00"` for end-of-day, and an `until` at or before `from` wraps past midnight. An empty array means 24/7. | | `rotations` | array | **Full replacement** of the rotation groups, up to 50. Each: `{ members: string[] }`, up to 200 members. Array order is the rotation order; member order within a group is preserved. Every member must already be a member of the schedule's team. Omit the field to leave rotations untouched, sending `[]` removes them all. | Plus the cadence fields, `rotationMode`, `rotationRepeats`, `customRepeatUnit`, `customRepeatValue`, `autoRotationSize`, `roundRobinSize`, `startsOnTime`, `startsOnDayOfWeek`, `startsOnDateOfMonth`. They are documented once, with their allowed values, under [Rotation cadence](/api/incident-management/schedules#rotation-cadence). `teamId` and `tierId` are **not** patchable. Moving a schedule between teams or tiers would silently re-point who it pages, so it is not a partial update. ### How the cadence is validated Cadence fields are merged onto the schedule's current row and then validated **as a whole**, not field by field. That is what lets you patch a single field, say `roundRobinSize`, without re-sending the rest of the cadence, while still rejecting a combination that cannot work (for example `rotationRepeats: "weekly"` with no `startsOnDayOfWeek` anywhere in the effective config). Validation happens before anything is written. A cadence the materializer would choke on never reaches the database. ### When shifts are recomputed Changing the timezone, the validity range, the weekly windows, any cadence field, or the rotations re-materializes the schedule's shifts. A bare rename does not, it would take the schedule's lock and rewrite rows for nothing. ## Example (cURL) ```bash curl -X PATCH "$BASE_URL/api/im/schedules/7" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "rotationMode": "explicit", "rotationRepeats": "custom", "customRepeatUnit": "minutes", "customRepeatValue": 30, "startsOnTime": "09:00", "rotations": [ { "members": ["u_abc123"] }, { "members": ["u_def456"] } ] }' ``` ## Response `200 OK`: the schedule's configuration after the update. ```json { "id": 7, "displayName": "Primary On-Call", "timezone": "Europe/Berlin", "effectiveFrom": "2026-08-01T00:00:00.000Z", "effectiveUntil": null, "weeklySchedules": [], "rotat…
### User Notification Settings
URL: https://docs.uptimeify.io/api/incident-management/user-notification-settings
Description: Organization admins read and set one person's notification settings: phone number, delivery channels and the whole notification chain.
Summary: `GET /api/im/users/:userId/notification-settings` · `PUT /api/im/users/:userId/notification-settings` An organization admin sets up how a person is paged, for example while onboarding a new on-call responder, so the person does not have to do it themselves. These are the same settings the person sees and edits under [Personal notification settings](/api/incident-management/notification-settings). **The last write wins**: the person can change everything afterwards, and an admin can set it again at any time. The person sees a notice "Changed by (admin) on (date)" on their notification page. `sms` and `voice` steps are stored even while the phone number is not verified. They wait: every page until then is logged as skipped (reason `unverified`), and the person is asked to confirm the number when they next sign in. Nothing is sent to a number nobody has confirmed. ## Authentication Requires the `admin` role of the organization, with a user session or an organization-wide API token (the token runs with the role of the user who created it). Customer-bound tokens and customer logins are refused. Incident Management must be enabled for the organization. The target user must belong to your organization, be active, and have an IM-eligible role (`admin`, `editor` or `responder`). ## Get a user's settings `GET /api/im/users/:userId/notification-settings` Creates the settings on first access, starting from the [default notifications](/api/incident-management/notification-template), exactly as when the person opens them. ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/users/usr_8f2c/notification-settings" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ### Response ```json { "userId": "usr_8f2c", "id": 31, "phoneNumber": "+491701234567", "phoneVerified": false, "channels": { "push": true, "sms": true, "voice": false, "email": true }, "severityChannels": {}, "rules": [ { "id": 201, "urgency": "high", "delayMinutes": 0, "channel": "push" }, { "id": 202, "urgency": "high", "delayMinutes": 5, "channel": "sms" }, { "id": 203, "urgency": "low", "delayMinutes": 0, "channel": "email" } ], "lastAdminChangeAt": "2026-10-28T09:12:00.000Z", "lastAdminChangeBy": { "id": "usr_admin", "name": "Ada Admin" } } ``` `phoneVerified: false` with `sms`/`voice` rules means those steps wait for the person to confirm the number. The severity filter (`severityChannels`) is shown but not set here; it stays the person's own choice. ## Set a user's settings `PUT /api/im/users/:userId/notification-settings` Replaces the person's **whole** notification chain with `rules`. Rules not in the list are deleted. A request that changes nothing writes nothing and does not update `lastAdminChangeAt`. ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `rules` | array | Yes | The whole chain, at most 64 steps. Each step `{ "urgency": "high" or "low", "delayMinutes": 0..1440, "channel": "push", "sms", "voice" or "email" }`. Each urgency/delay/channel combination at most once. An empty list removes every rule. | | `channels` | object | No | The four delivery switches (`push`, `sms`, `voice`, `email` → boolean). Omitted: a channel is on exactly when `rules` has a step for it. Other switches the person set (shift reminders) are kept. | | `phoneNumber` | string or null | No | E.164 number, e.g. `+491701234567`. Omitted: unchanged. `null` removes it. A different number is unverified until the person confirms it, and any pending verification code is discarded. | Unknown fields are rejected. ### Example (cURL) ```bash curl -X PUT "$BASE_URL/api/im/users/usr_8f2c/notification-settings" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"phoneNumber":"+491701234567","rules":[{"urgency":"high","delayMinutes":0,"channel":"push"},{"urgency":"high","delayMinutes":5,"channel":"sms"},{"urgency":"low","delayMinutes":0,"channel":"email"}]}' ``` ### Response `200 OK`: the settings after…
### Introduction
URL: https://docs.uptimeify.io/api/introduction
Description: Welcome to the Uptimeify API documentation. With this REST API, you can programmatically manage your monitoring infrastructure: e.g., organizations, customers, websites, and alerts.
Summary: ## Base URL All API requests should be sent to the following base URL: ```text https://uptimeify.io/api ``` ## Authentication The API supports **Bearer Token** authentication for integrations. ### Create API Token 1. Log in to the Uptimeify dashboard. 2. Open **Settings** > **API** in the dashboard. 3. Click on **Create Token**, enter a name, and copy the generated secret. Add the token to the `Authorization` header of your requests: ```http Authorization: Bearer wsm_ ``` The token is a single line: copy it without spaces or line breaks. The scheme is case-insensitive (`Bearer` or `bearer`) and spaces around the token are ignored, but a token with a space inside is rejected with `401 Unauthorized`. Uptimeify API tokens always start with `wsm_`. If your token does not have that prefix, you are likely using the wrong credential (and requests will return `401 Unauthorized`). ### Token Scopes (Organization vs Customer) API tokens can optionally be created with a **Customer Scope**: - **Organization-wide Token**: can read/modify resources across all customers of the organization. - **Customer-Scoped Token**: can only read/modify resources (websites, maintenance windows, etc.) within that specific customer. Customer-scoped tokens are recommended for agencies and external integrations. Requests outside the scope return `403 Forbidden`. > **Note:** Session-based authentication (cookies) is used for the web interface but is not recommended for integrations. ## Response Format All responses are returned in JSON format. ### Success Response ```json { "id": 123, "name": "example-resource", "createdAt": "2023-01-01T12:00:00Z" } ``` ### Error Response Errors are returned with an appropriate HTTP status code and a JSON body containing details. ```json { "statusCode": 400, "statusMessage": "Bad Request", "message": "Validation failed: 'url' is required." } ``` ## Rate Limiting To ensure service stability, the API is rate-limited. - **Limit**: 600 requests per minute per IP - **Header**: `X-RateLimit-Remaining` shows your remaining quota - **Exceeded**: `429 Too Many Requests` ## Pages - [Generate API Token](/api/introduction/generate-api-token) - [Token Scopes (Organization vs Customer)](/api/introduction/token-scopes-organization-vs-customer) - [Success Response](/api/introduction/success-response) - [Error Response](/api/introduction/error-response)
### Error Response
URL: https://docs.uptimeify.io/api/introduction/error-response
Description: Errors are returned with an appropriate HTTP status code and a JSON body containing details.
Summary: ```json { "statusCode": 400, "statusMessage": "Invalid request body", "data": { "code": "invalidRequestBody", "issues": [{ "path": "url", "message": "Invalid input: expected string, received undefined" }], "requestId": "3f2b6c1e-8a4d-4f0e-9b7a-2c5d1e6f7a8b" } } ``` - `data.code` names the error. Branch on it, never on the text; the codes are listed in the error code list. - `data.issues` (only for `invalidRequestBody`) lists each rejected field with `path` (dot-joined) and `message`. - `data.requestId` identifies this one request. Quote it when you contact support. - `statusMessage` is English and says what to change: which role, token or scope is missing, or which field is wrong. It may be reworded; never parse it. - `data.requiredScope` (only for `apiTokenScopeForbidden`) names the scope the token lacks; `data.reason` (only for `agentTokenReadOnly`) says which agent-token rule refused the call. - Which role and token an endpoint needs: [Permissions by endpoint](/api/introduction/permissions-by-endpoint). ## Request ID Every API response carries an `X-Request-ID` header. Send your own `X-Request-ID` (1 to 128 characters from `A-Z`, `a-z`, `0-9`, `.`, `_`, `:`, `-`), for example your CI run, and the API echoes it back and uses it in `data.requestId`; otherwise it generates a UUID. A value outside that format is replaced, not rejected. ## Rate limiting To ensure service stability, the API is rate-limited. - **Limit**: 600 requests per minute per IP - **Header**: `X-RateLimit-Remaining` shows your remaining quota - **Exceeded**: `429 Too Many Requests`
### Generate API Token
URL: https://docs.uptimeify.io/api/introduction/generate-api-token
Description: Step-by-step guide to generating an Uptimeify API token from the dashboard Settings > API page.
Summary: 1. Log in to the Uptimeify dashboard. 2. Open **Settings** > **API** in the dashboard. 3. Click **Create Token**, enter a name, and copy the generated secret. Add the token to the `Authorization` header of your requests: ```http Authorization: Bearer wsm_ ``` The token is a single line: copy it without spaces or line breaks. The scheme is case-insensitive (`Bearer` or `bearer`) and spaces around the token are ignored, but a token with a space inside is rejected with `401 Unauthorized`. Uptimeify API tokens always start with `wsm_`. If your token does not have that prefix, you are likely using the wrong credential.
### Permissions by endpoint
URL: https://docs.uptimeify.io/api/introduction/permissions-by-endpoint
Description: Which role, token type and token scope each endpoint needs, and which error code a refused call returns.
Summary: Every call is checked in this order. The first check that fails decides the answer: 1. **Authentication.** No token, or a revoked, expired or mistyped one: `401 unauthorized`. 2. **Token type.** A customer-bound token on an organization-wide path: `403 customerScopedTokenForbidden`. A token with scopes that lacks the scope of the path: `403 apiTokenScopeForbidden`. The message and `data.requiredScope` name the missing scope, for example `api.write.monitors`. See [Token Scopes](/api/introduction/token-scopes-organization-vs-customer). 3. **Role.** An organization API token (`wsm_…`) acts with the **current** role of the user who created it. If that user is deactivated or deleted, the token acts as `readonly`. Old tokens without a recorded issuer act as `admin`. A role that is not allowed gets `403` with the code in the table below. 4. **Customer scope.** `readonly` users, editors assigned to customers and customer-bound tokens only reach their own customers. A specific resource outside that scope answers `404` with the resource's not-found code, never `403`. An API token, organization-wide or customer-bound, follows the **current** role and customer assignment of the user who created it: if that user is assigned to customers, the token reaches only those customers (a customer-bound token reaches its customer only while that user still has it). If the user is deactivated or deleted, the token reaches no customer at all. 5. **Module.** Status pages need the status pages module (`403 statusPagesModuleDisabled`). Incident Management must be enabled for the organization (`403 imNotEnabled`). Every refused call carries a stable `data.code` and an English `statusMessage` that says what is missing. Branch on the code; the message may be reworded. Roles: `admin` and `editor` are organization roles, `readonly` is the customer self-service role, `responder` exists for Incident Management only. Global supporters never change customer data (`403 forbidden`). Agent tokens (`wsma_…`, connected apps) reach only the paths their scopes allow; every other path answers `403 agentTokenReadOnly` with `data.reason`. ## Monitors | Method | Path | Who may call it | Scope | Refused with | |---|---|---|---|---| | `GET` | `/api/websites/:id`, `/api/-monitors/:id` | Any role within its customer scope | `api.read.monitors` | `404 websiteNotFound` / `monitorNotFound` | | `POST` | `/api/websites`, `/api/-monitors` | `admin`, `editor`. `readonly` and customer-bound tokens create `self_service` monitors for their own customer if the package allows self-service. Only `admin` may set `managementType`. | `api.write.monitors` | `forbidden`, `selfServiceNotAllowed`, `selfServiceQuotaReached`, quota codes | | `PATCH` | `/api/websites/:id`, `/api/-monitors/:id` | `admin`, `editor`. Customer-bound callers change `self_service` monitors, `managed` ones only with `canEditManaged`. Changing `managementType` needs an organization-wide `admin`. | `api.write.monitors` | `forbidden`, `managed_by_organization`, `managementTypeOrgOnly` | | `DELETE` | `/api/websites/:id`, `/api/-monitors/:id` | Like `PATCH`, but never `readonly` (nor a token its user created) | `api.write.monitors` | `readonlyMayNotDelete`, `managed_by_organization` | | `POST` | `/api/websites/:id/heartbeat-token/rotate` | Like `PATCH` | `api.write.monitors` | as `PATCH` | | `GET`, `POST`, `DELETE` | `/api/monitor-tags` | Any role within its customer scope | `api.read.monitors` / `api.write.monitors` | `forbidden`, `badRequest` | | `GET` | `/api/tags`, `/api/tags/:id` | Any role in the organization | `api.read.monitors` | `404 tagNotFound` | | `POST`, `PATCH`, `DELETE` | `/api/tags`, `/api/tags/:id` | Any role; customer-bound callers create and change tags of their customers only, never organization-wide tags | `api.write.monitors` | `forbidden`, `authorizingUserUnresolved` | | `GET` | `/api/maintenance-windows/:id` | Any role within its customer scope | `api.read.monitors` | `forbidden`…
### Success Response
URL: https://docs.uptimeify.io/api/introduction/success-response
Description: On success, the API returns a JSON body with the requested data.
Summary: ```json { "id": 123, "name": "example-resource", "createdAt": "2023-01-01T12:00:00Z" } ```
### Token Scopes (Organization vs Customer)
URL: https://docs.uptimeify.io/api/introduction/token-scopes-organization-vs-customer
Description: API tokens can optionally be created with a Customer Scope:
Summary: - **Organization-wide token**: can read/modify resources across all customers of the organization. - **Customer-scoped token**: can only read/modify resources (websites, maintenance windows, etc.) within that specific customer. Customer-scoped tokens are recommended for agencies and external integrations. Requests outside the scope return `403 Forbidden`. A customer-scoped token never reaches organization-wide paths, regardless of HTTP method: organization settings and billing (`/api/organizations/**`, `/api/organization/**` except `GET /api/organization`), users, admin and platform-admin routes, escalation configuration, custom pricing and custom fields, Incident Management, creating or deleting customers. Such calls answer `403` with `data.code: customerScopedTokenForbidden`. Reading `/api/organization` and `/api/package-configs` stays possible. No API token can create another token. ## Roles and the customer scope Every request carries two things: a **role** (what kind of writes the actor may make) and a **customer scope** (which customers the actor sees). The scope is decided by the token's customer binding, or, for a user session, by the customer assignments of that user. Both must allow a call. | Role | Who | Scope | |---|---|---| | `admin` | Organization administrator | Organization-wide, always. | | `editor` | Organization team member | Organization-wide unless the user is assigned to specific customers; then confined to those. | | `readonly` | **Customer self-service** user | Always confined to the customers the user is assigned to. | `readonly` is the self-service role a customer works with. Inside its own customer scope it may **read and write**: monitors, maintenance windows for its customer, notification channels of its customer, and so on. What it can never do is touch **organization-wide resources**: org-wide (tag-only) maintenance windows, organization settings and billing, users, creating customers. `editor` and `admin` are the organization roles; an `editor` that is assigned to customers is treated exactly like a customer-bound actor on those organization-wide resources. Concretely, an actor with a restricted scope (a customer-scoped token, a `readonly` user, an `editor` with customer assignments) gets `403` with `data.code: customerScopedTokenForbidden` on: - creating a customer (`POST /api/customers`) - editing or deleting an **org-wide** maintenance window (`PATCH`/`DELETE /api/maintenance-windows/:id` on a window without a customer) - organization settings, billing, users and the other paths listed above and a tag-only maintenance window it creates is anchored to its single customer instead of becoming org-wide (see [Create Maintenance Window](/api/maintenance-windows/create)). ## A resource outside your scope is a `404` `403` is reserved for **what you may do**: a role that may not write, a customer-scoped token on an organization path, a managed monitor. A **specific resource** that exists but belongs to another customer or another organization is, for you, indistinguishable from one that does not exist: the API answers `404` with the same `data.code` as for a missing id (`websiteNotFound`, `monitorNotFound`, `customerNotFound`, `statusPageNotFound`, …). Do not treat a `404` as proof that an id is free, and do not expect a `403` to tell you that something exists. ## Permission scopes (least privilege) Independently of the customer binding, a token can be limited to **scopes** when it is created (`scopes` on [Create Organization Token](/api/api-tokens/create-organization-token) and [Create Customer Token](/api/api-tokens/create-customer-token)). A token without scopes (`scopes: null`, every token created before 24.10.2026 and every token created without a selection) keeps **full access**, exactly as before. A scope is `api.read.` (methods `GET` and `HEAD`) or `api.write.` (every other method). Write does not include read: a token that creates monitors and lists them needs both `api.read.monit…
### Maintenance Windows
URL: https://docs.uptimeify.io/api/maintenance-windows
Description: Create and manage maintenance windows to suppress alerts during planned work. Windows can target a single monitor, multiple monitors, an entire customer, or any monitor carrying a given tag.
Summary: Maintenance windows suppress alerts for the covered monitors during a planned time range. While a window is active the affected monitor is treated as **in maintenance**: no alerts are fired and, if the customer has a status page, the service is shown as **Maintenance** instead of **Degraded**. ## Targeting options A window can cover monitors in four ways (mutually exclusive, except that `targets` and `tagIds` may be combined): | Mode | How to specify | |------|----------------| | **Single monitor (legacy)** | One of the legacy ID fields: `websiteId`, `icmpMonitorId`, `smtpMonitorId`, `sshMonitorId`, `tcpMonitorId`, `ftpMonitorId`, `imapPopMonitorId`, `dnsMonitorId`, `customerIpId`, `customerDomainId` | | **Multiple monitors** | `targets: [{ type, id }, ...]` array | | **By tag (dynamic)** | `tagIds: [number, ...]`: covers all monitors of the window's customer that currently carry the tag; future-tagged monitors are auto-covered | | **Customer-level** | `customerId` alone: covers every monitor belonging to that customer | ## Dynamic tag behavior Tag-based windows are evaluated live by the monitoring worker: every time a check result arrives the worker resolves which maintenance windows apply to that monitor by looking up the monitor's current tags. This means a monitor tagged *after* a window is created is automatically covered without updating the window. Removing a tag from a monitor drops it from coverage instantly. Tag windows are anchored to a single customer. You cannot create an organization-wide tag window that spans multiple customers. ## Endpoints - [List Maintenance Windows](/api/maintenance-windows/list) - [Create Maintenance Window](/api/maintenance-windows/create) - [Get Maintenance Window](/api/maintenance-windows/get) - [Update Maintenance Window](/api/maintenance-windows/update) - [Delete Maintenance Window](/api/maintenance-windows/delete)
### Create Maintenance Window
URL: https://docs.uptimeify.io/api/maintenance-windows/create
Description: Creates a new maintenance window. Accepts a single monitor (legacy), multiple monitors, tag-based (including org-wide), or customer-level targeting.
Summary: `POST /api/maintenance-windows` ## Body ```json { "name": "Database migration", "startTime": "2026-07-10T22:00:00.000Z", "endTime": "2026-07-11T01:00:00.000Z", "targets": [ { "type": "website", "id": "ef8a6564-0ccf-4f3f-a5ef-d2963176b3eb" }, { "type": "icmp", "id": "3d005a18-fdd8-4dc7-9f26-1a9d409c1bc5" } ], "tagIds": [7], "description": "Planned schema migration", "isRecurring": false, "isActive": true } ``` ### Required fields - `name` (string): A friendly label for the window. - `startTime` (ISO 8601 datetime): When the window begins. - `endTime` (ISO 8601 datetime): When the window ends. Must be after `startTime`. - **At least one targeting field** (see below). ### Target selection (mutually exclusive modes) Exactly one targeting mode must be used. `targets` and `tagIds` may be combined within the multi-monitor mode. | Field | Type | Description | |-------|------|-------------| | `websiteId` | number | Legacy: single website monitor | | `icmpMonitorId` | number | Legacy: single ICMP monitor | | `smtpMonitorId` | number | Legacy: single SMTP monitor | | `sshMonitorId` | number | Legacy: single SSH monitor | | `tcpMonitorId` | number | Legacy: single TCP monitor | | `ftpMonitorId` | number | Legacy: single FTP monitor | | `imapPopMonitorId` | number | Legacy: single IMAP/POP monitor | | `dnsMonitorId` | number | Legacy: single DNS monitor | | `customerIpId` | number | Legacy: single customer IP | | `customerDomainId` | number | Legacy: single customer domain | | `targets` | `{ type, id }[]` | Multi-monitor: `type` is one of `website` \| `dns` \| `icmp` \| `smtp` \| `ssh` \| `tcp` \| `ftp` \| `imap_pop` \| `customer_domain` \| `customer_ip`. `id` is the monitor's public id (UUID), the same identifier the legacy single-target fields take; a numeric row id is still accepted. | | `tagIds` | number[] | Tag-based: see [Tag-only (org-wide) mode](#tag-only-org-wide-mode) below | | `customerId` | number | Customer-level: covers every monitor of that customer | ### Tag-only (org-wide) mode Sending `tagIds` **without** `customerId`, `targets`, or any legacy field creates an **org-wide** maintenance window. The window dynamically covers every monitor across the entire organization that currently carries the specified tags, across all customers. ```json { "name": "Infra tag freeze", "startTime": "2026-07-10T22:00:00.000Z", "endTime": "2026-07-11T01:00:00.000Z", "tagIds": [7] } ``` - **Requires an organization-wide admin or editor**: the role AND an unrestricted customer scope. A customer-bound actor (a `readonly` user, an `editor` assigned to customers, a customer-scoped token) does not get an org-wide window: when it is bound to exactly one customer, the window is anchored to that customer and covers only that customer's tagged monitors; when it is bound to several (or none), the request is rejected with `400 tagOnlyNeedsCustomer` and it must select monitors or a customer instead. See [Roles and the customer scope](/api/introduction/token-scopes-organization-vs-customer). - The tag membership is resolved live at check time: monitors tagged after the window is created are automatically covered. - All `tagIds` must belong to the same organization; mixing tags from different organizations returns `400 mixedTagOrganizations`. ### Combination rules - **Minimum one** targeting field is required. Omitting all is a Zod validation error (standard `400` with a validation body, not a `data.code` error). - **`customerId` (customer-level mode)** cannot be combined with `targets`, `tagIds`, or any legacy field. Combining them is a Zod validation error (standard `400`). - All monitors in `targets` must belong to the **same customer**; mixing customers returns `{ data: { code: "mixedCustomers" } }`. - All `tagIds` must belong to the same organization; mixing organizations returns `{ data: { code: "mixedTagOrganizations" } }`. ### Optional fields | Field | Type | Description | |-------|------|-------------| | `description` | string | Free-text notes (sh…
### Delete Maintenance Window
URL: https://docs.uptimeify.io/api/maintenance-windows/delete
Description: Permanently deletes a maintenance window. Active alert suppression ends immediately.
Summary: `DELETE /api/maintenance-windows/{id}` ## Path Parameters - `id` (required): The numeric ID of the maintenance window to delete. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X DELETE "$BASE_URL/api/maintenance-windows/42" \ -H "Authorization: Bearer $TOKEN" ``` ## Response Returns `204 No Content` on success with an empty body. ## Common errors - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the organization or the window is out of scope (global supporter accounts cannot delete maintenance windows) - `403` with `data.code: customerScopedTokenForbidden` when the window is org-wide (no customer) and you are a customer-bound actor: a `readonly` user, an `editor` with customer assignments, or a customer-scoped token. Only an organization-wide admin or editor deletes org-wide windows; see [Roles and the customer scope](/api/introduction/token-scopes-organization-vs-customer) - `404 Not Found` when no maintenance window with the given ID exists
### Get Maintenance Window
URL: https://docs.uptimeify.io/api/maintenance-windows/get
Description: Returns a single maintenance window by ID, including its full target and tag selection.
Summary: `GET /api/maintenance-windows/{id}` ## Path Parameters - `id` (required): The numeric ID of the maintenance window. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/maintenance-windows/42" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "id": 42, "publicId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "organizationId": 10, "customerId": 1, "name": "Weekly deployment", "description": "Rolling update every Monday", "startTime": "2026-07-07T02:00:00.000Z", "endTime": "2026-07-07T04:00:00.000Z", "isRecurring": true, "recurrencePattern": { "frequency": "weekly", "intervalCount": 1, "daysOfWeek": [1] }, "isActive": true, "timezone": "UTC", "targets": [ { "type": "website", "id": 101 }, { "type": "icmp", "id": 5 } ], "tags": [ { "id": 7, "publicId": "0b0e4c3e-9a1f-4d3e-8a2b-1c2d3e4f5a6b", "name": "Production", "color": "red" } ], "websiteId": null, "icmpMonitorId": null, "smtpMonitorId": null, "sshMonitorId": null, "tcpMonitorId": null, "ftpMonitorId": null, "imapPopMonitorId": null, "dnsMonitorId": null, "customerIpId": null, "customerDomainId": null, "createdAt": "2026-06-01T09:00:00.000Z", "updatedAt": "2026-06-01T09:00:00.000Z" } ``` The `targets` array lists all explicitly selected monitors. The `tags` array lists the tags whose monitors are dynamically covered, each as `{ id, publicId, name, color }`; the tag owner is not part of this response. Both may be non-empty simultaneously when the window uses a mixed multi-monitor + tag selection. `websiteSummary` (`{ id, publicId, name, url }` or `null`) names the legacy target website; `website` (the full website row) is deprecated in favour of it. **Deprecated field:** `recurrencePattern.interval` is still sent next to `recurrencePattern.intervalCount` until it is removed on 2027-01-18. Read `intervalCount`. ## Common errors - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the organization or the window belongs to an out-of-scope customer - `404 Not Found` when no maintenance window with the given ID exists
### List Maintenance Windows
URL: https://docs.uptimeify.io/api/maintenance-windows/list
Description: Returns all maintenance windows visible to the authenticated user, scoped by organization and optional customer filter.
Summary: `GET /api/maintenance-windows` ## Query Parameters - `customerId` (optional): Filter windows by customer ID. - `organizationId` (optional): Defaults to your session organization. - `envelope` (optional): `items` answers `{ items, total, page, perPage }` instead of the bare array, all windows on one page. This list form becomes the default on 2027-01-18; the bare array is deprecated. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/maintenance-windows?customerId=1" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json [ { "id": 42, "publicId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "organizationId": 10, "customerId": 1, "name": "Weekly deployment", "description": "Rolling update every Monday", "startTime": "2026-07-07T02:00:00.000Z", "endTime": "2026-07-07T04:00:00.000Z", "isRecurring": true, "recurrencePattern": { "frequency": "weekly", "intervalCount": 1, "daysOfWeek": [1] }, "isActive": true, "timezone": "UTC", "targets": [ { "type": "website", "id": 101 }, { "type": "icmp", "id": 5 } ], "tags": [ { "id": 7, "publicId": "0b0e4c3e-9a1f-4d3e-8a2b-1c2d3e4f5a6b", "name": "Production", "color": "red" } ], "websiteId": null, "icmpMonitorId": null, "smtpMonitorId": null, "sshMonitorId": null, "tcpMonitorId": null, "ftpMonitorId": null, "imapPopMonitorId": null, "dnsMonitorId": null, "customerIpId": null, "customerDomainId": null, "createdAt": "2026-06-01T09:00:00.000Z", "updatedAt": "2026-06-01T09:00:00.000Z" } ] ``` Each window includes: - `targets`: array of `{ type, id }` objects for all explicitly selected monitors (`type` is one of `website` | `dns` | `icmp` | `smtp` | `ssh` | `tcp` | `ftp` | `imap_pop`). - `tags`: array of tag objects `{ id, publicId, name, color }` for tag-based coverage; an empty array when the window does not use tag targeting. The tag owner (`createdBy`) is not part of this response. - `websiteSummary`: `{ id, publicId, name, url }` of the legacy target website, or `null`. `website` (the full website row) is deprecated in favour of it. - Legacy single-target fields (`websiteId`, `icmpMonitorId`, etc.) remain present for backwards compatibility; they are `null` when multi-target or tag-based selection is used. **Deprecated field:** `recurrencePattern.interval` is still sent next to `recurrencePattern.intervalCount` until it is removed on 2027-01-18. Read `intervalCount`. ## Visibility Which windows come back depends on who is reading, not only on the query parameters: - An **unrestricted reader** (organization admin, global admin, and an organization-bound agent token) receives every window of the organization: the customer-anchored ones and the organization-wide ones (`customerId: null`). - A **customer-scoped reader** (a `readonly` user assigned to one or more customers, and the agent token minted for such a user) receives the windows of their own customers plus the organization-wide ones. Windows belonging to another customer are never returned. - A **customer-scoped API token** is pinned to the customer it was issued for and receives that customer's windows only. Passing `customerId` explicitly narrows the result further. A `readonly` user may only name a customer they are assigned to; any other customer answers `403 Forbidden`. ## Common errors - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the organization
### Preview Tag Coverage Count
URL: https://docs.uptimeify.io/api/maintenance-windows/preview-count
Description: Returns how many distinct monitors a set of tags currently covers, for the tag-only (org-wide) maintenance-window mode.
Summary: `POST /api/maintenance-windows/preview-count` Used by the maintenance-window form to show "this will cover N monitors" before submitting a [tag-only (org-wide) window](/api/maintenance-windows/create#tag-only-org-wide-mode). Coverage is resolved live: it counts every monitor, across every monitor type, currently tagged with at least one of the given tags, the same dynamic membership the org-wide window itself uses at check time. ## Body ```json { "tagIds": [7] } ``` ### Fields | Field | Type | Description | |-------|------|-------------| | `tagIds` | number[] | Required, at least one. Tags to count coverage for. Must belong to your organization. | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/maintenance-windows/preview-count" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "tagIds": [7] }' ``` ## Response ```json { "count": 12 } ``` `count` is the number of distinct `(monitorType, monitorId)` pairs currently carrying at least one of the given tags, not the number of tags. ## Common errors | Status | Description | |--------|-------------| | `400` (validation) | `tagIds` is missing or empty. Standard Zod validation error body, not `{ data: { code } }`. | | `401 Unauthorized` | Not logged in. | | `404` `{ data: { code: "tagNotFound" } }` | A `tagId` does not exist in your organization, or you cannot see it. |
### Preview Maintenance Occurrences
URL: https://docs.uptimeify.io/api/maintenance-windows/preview-occurrences
Description: Computes the upcoming occurrences of a (not-yet-saved) recurrence pattern, without creating a window.
Summary: `POST /api/maintenance-windows/preview-occurrences` Pure computation: this endpoint never touches the database. It runs the same zone-aware recurrence engine the alert-suppression path uses (`occurrencesInRange`), so the preview can never drift from what a saved window with the same `startTime`/`endTime`/`recurrencePattern`/ `timezone` will actually suppress. Useful for showing "what does this pattern mean" before submitting [Create Maintenance Window](/api/maintenance-windows/create) or [Update Maintenance Window](/api/maintenance-windows/update). ## Body ```json { "startTime": "2026-08-10T02:00:00.000Z", "endTime": "2026-08-10T03:00:00.000Z", "isRecurring": true, "recurrencePattern": { "frequency": "weekly", "intervalCount": 1, "daysOfWeek": [1, 3] }, "timezone": "Europe/Berlin" } ``` ### Fields | Field | Type | Description | |-------|------|-------------| | `startTime` | ISO 8601 datetime | Required. Start of the first occurrence. | | `endTime` | ISO 8601 datetime | Required. End of the first occurrence. Must be after `startTime`. | | `isRecurring` | boolean | Required. When `false`, the response contains only the single anchor occurrence. | | `recurrencePattern` | object | Required when `isRecurring` is `true`. Same shape as [Create Maintenance Window](/api/maintenance-windows/create#recurrence). | | `timezone` | string | Default `"UTC"`. The IANA zone the pattern is interpreted in, same validation and canonicalization as the `timezone` field on create/update. | The response returns at most 5 upcoming occurrences, looking forward up to 5 years from the current time. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/maintenance-windows/preview-occurrences" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "startTime": "2026-08-10T02:00:00.000Z", "endTime": "2026-08-10T03:00:00.000Z", "isRecurring": true, "recurrencePattern": { "frequency": "weekly", "intervalCount": 1, "daysOfWeek": [1, 3] }, "timezone": "Europe/Berlin" }' ``` ## Response ```json { "occurrences": [ { "start": "2026-08-10T00:00:00.000Z", "end": "2026-08-10T01:00:00.000Z" }, { "start": "2026-08-12T00:00:00.000Z", "end": "2026-08-12T01:00:00.000Z" }, { "start": "2026-08-17T00:00:00.000Z", "end": "2026-08-17T01:00:00.000Z" } ] } ``` `occurrences` may be an empty array (e.g. a recurrence pattern whose `endRecurrenceDate` has already passed relative to the preview horizon). Sending `isRecurring: true` without a `recurrencePattern` is not an error. The window is treated as non-recurring and the response contains only the single occurrence described by `startTime` and `endTime`, the same fallback the recurrence engine applies to a malformed pattern. **Deprecated field:** until 2027-01-18 responses still carry `recurrencePattern.interval` next to `recurrencePattern.intervalCount` and request bodies still accept it. Send `intervalCount`; both with different values answer `400` `invalidRequestBody`. ## Common errors | Status | Description | |--------|-------------| | `400` (validation) | `timezone` is a raw UTC offset or not a zone name the runtime recognizes. Standard Zod validation error body, not `{ data: { code } }`. | | `400` `{ data: { code: "invalidWindow" } }` | `endTime` is not after `startTime`. | | `401 Unauthorized` | Not logged in. |
### Update Maintenance Window
URL: https://docs.uptimeify.io/api/maintenance-windows/update
Description: Partially updates a maintenance window. All fields are optional; only supplied fields are changed. When targets or tagIds are provided they replace the existing selection entirely.
Summary: `PATCH /api/maintenance-windows/{id}` ## Path Parameters - `id` (required): The numeric ID of the maintenance window to update. ## Body All fields are optional. Omit a field to leave it unchanged. ```json { "name": "Extended deployment window", "endTime": "2026-07-11T03:00:00.000Z", "targets": [ { "type": "website", "id": "ef8a6564-0ccf-4f3f-a5ef-d2963176b3eb" }, { "type": "dns", "id": "5b0d88a6-397d-4acd-b69f-c31405d7d0da" } ], "tagIds": [7, 12], "isActive": true } ``` ### Updatable fields | Field | Type | Notes | |-------|------|-------| | `name` | string | Display label | | `description` | string | Free-text notes | | `startTime` | ISO 8601 datetime | New start time | | `endTime` | ISO 8601 datetime | New end time; must be after `startTime` | | `isActive` | boolean | Enable or disable without deleting | | `isRecurring` | boolean | Toggle recurrence | | `recurrencePattern` | object | Replaces the recurrence pattern; structure identical to create | | `timezone` | string | The IANA zone (e.g. `"Europe/Berlin"`) the recurrence pattern is interpreted in. Case-insensitive spellings and legacy IANA link names (e.g. `"gmt"`, `"Zulu"`) are accepted and stored under the runtime's canonical name, `"utc"` and `"Zulu"` are both stored as `"UTC"`. A raw UTC offset (e.g. `"+05:00"`) is rejected: it carries no daylight-saving rule, so it cannot express what a zone name does. | | `targets` | `{ type, id }[]` | **Replaces** the full set of explicit monitor targets. `id` is the monitor's public id (UUID); a numeric row id is still accepted. | | `tagIds` | number[] | **Replaces** the full set of tag IDs | | `websiteId` / `icmpMonitorId` / … | number \| null | Legacy single-target fields | | `customerId` | number | Customer anchor (only for tag-only windows) | ### Replace semantics for targets and tagIds When `targets` or `tagIds` is included in the request body, the **entire existing selection** for that field is replaced. To remove all explicit targets send `"targets": []`; to remove all tags send `"tagIds": []`. ### Combination rules PATCH validates target and tag scope using the same resolver as create, but does **not** re-run the create-time Zod superRefine. In practice: - `customerId` cannot be combined with `targets`, `tagIds`, or legacy fields. - All monitors in `targets` must belong to the same customer; mixing returns `{ data: { code: "mixedCustomers" } }`. - An org-wide tag-only window (tags without `customerId`, `targets`, or legacy fields) can be edited only by an **organization-wide** admin or editor. A customer-bound actor (a `readonly` user, an `editor` assigned to customers, a customer-scoped token) receives `403` with `data.code: customerScopedTokenForbidden`, whatever it sends. - A window that already belongs to a customer stays with that customer: the existing customer seeds the resolver, so adding `tagIds` never turns it org-wide. ### Readonly users in scope Read-only users assigned to the window's customer may edit maintenance windows scoped to that customer (`readonly` is the customer self-service role, see [Roles and the customer scope](/api/introduction/token-scopes-organization-vs-customer)). Global supporter accounts cannot. No customer-bound actor, `readonly` or otherwise, can update an org-wide tag-only window. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PATCH "$BASE_URL/api/maintenance-windows/42" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"isActive": false}' ``` ## Response Returns the updated maintenance window object: the stored window fields plus `targets` (`{ type, id, name, publicId }[]`) and `tags` (`{ id, publicId, name, color }[]`) in the same shape as [Get Maintenance Window](/api/maintenance-windows/get), so a client can read back the selection it just replaced. ## Common errors | Status | Description | |--------|-------------| | `400` (validation) | Update would leave the window with no targets, `customerId` combined wi…
### MCP Server
URL: https://docs.uptimeify.io/api/mcp
Description: Use Uptimeify's free check tools from any AI agent over the Model Context Protocol (MCP).
Summary: Uptimeify exposes a stateless [Model Context Protocol](https://modelcontextprotocol.io) server so AI agents can run our free checks directly. For an overview of what the server can do and which clients it works with, see the [MCP server page on uptimeify.io](https://uptimeify.io/mcp-server). This page is the technical reference. ## Endpoint `POST https://uptimeify.io/mcp`: Streamable HTTP transport, stateless. The anonymous check tools need no authentication; the authenticated tools require a Bearer API token (see below). Discover the server programmatically via the MCP Server Card: `GET https://uptimeify.io/.well-known/mcp/server-card.json` **Browser origins.** Requests that carry an `Origin` header (that is, requests made by a web page in a browser) are accepted only from `https://uptimeify.io`. Any other origin gets HTTP `403` with the JSON-RPC error `data.code: "mcpOriginNotAllowed"`; this protects against DNS-rebinding attacks. MCP clients such as Claude, Cursor or `mcp-remote` send no `Origin` header and are not affected. ## Connect an MCP client Point any MCP client that speaks the **Streamable HTTP** transport at the endpoint above. - **Anonymous tools** work with just the URL: no token needed. - **Authenticated tools** require your Uptimeify API token as an `Authorization: Bearer ` header. Create one under **Settings → API tokens**: leave the customer field empty for an organization-wide token (sees all your monitors), or pick a customer to scope the token to that customer only. The token is shown **once** on creation: copy it right away. Clients that support remote HTTP MCP servers with custom headers can point at the URL directly: ```json { "mcpServers": { "uptimeify": { "url": "https://uptimeify.io/mcp", "headers": { "Authorization": "Bearer wsm_your_token_here" } } } } ``` For clients that only speak stdio, bridge to the HTTP endpoint with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote): ```json { "mcpServers": { "uptimeify": { "command": "npx", "args": ["-y", "mcp-remote", "https://uptimeify.io/mcp", "--header", "Authorization: Bearer wsm_your_token_here"] } } } ``` Omit the `Authorization` header entirely if you only need the anonymous check tools. ## Rate limits The anonymous tools run real network probes on your behalf, so they are capped per client IP. You do not need an account to hit these limits, and you do not need one to stay under them: | Scope | Limit | | --- | --- | | `POST /mcp` overall | 120 requests per minute per IP | | Each anonymous check tool | 15-30 calls per minute per IP, depending on how expensive the probe is (`whois` and `domain_expiry` are the strictest at 15) | | Each authenticated read tool | 60 calls per minute per IP | | Each authenticated write tool | 10 calls per minute **per organization**, not per IP -- writing is rarer and costlier than reading, and a model retrying a write in a loop should hit this quickly on purpose | The two layers apply together: 120 calls a minute spread across different tools is fine, 120 calls a minute of `whois` is not. Exceeding a limit returns HTTP `429` with a `retryAfter` value in seconds, telling you when the current window ends. Windows are fixed, not sliding, so a client that waits out `retryAfter` gets a full fresh allowance. The limits are enforced per IP, not per token: an API token does not raise the ceiling, and running several agents behind one NAT address makes them share it. If you have a use case that genuinely needs more, [get in touch](https://uptimeify.io/contact) rather than working around it. ## Available tools All tools are anonymous and read-only. They mirror our public web tools: - **check_ssl**: TLS/SSL certificate inspection (`host`, optional `port`) - **check_dns**, **dns_propagation**, **mx_lookup**: DNS resolution and propagation (`domain`) - **spf_check**, **dkim_check** (`domain`, `selector`), **dmarc_check**: mail authentication (`domain`) - **dnsbl_check** (`ip`), **whois** (`domain`), **domain_expiry** (`…
### Monitoring Data & Reports
URL: https://docs.uptimeify.io/api/monitoring
Description: API endpoints for retrieving monitoring data, check history, incident details, uptime stats, and PDF reports.
Summary: ## Monitoring Data ### Get Uptime Stats `GET /api/websites/:websitePublicId/uptime-stats` Returns uptime percentages and average response times (day/month/year). ### Get Check History `GET /api/websites/:websitePublicId/check-history` Returns the latest monitoring checks for a website. ### Get Incident History `GET /api/websites/:websitePublicId/incident-history` Returns incidents for a website (latest 100). ### Get Alert History `GET /api/websites/:websitePublicId/alert-history` Returns notification/escalation attempts for incidents of a website. ### Get Monitoring Data `GET /api/websites/:websitePublicId/monitoring-data?range=day|week|month|year` Returns aggregated time series data used for charts. ### Get Incident Details `GET /api/incidents/:incidentPublicId` Returns details of a specific incident. ### List Incidents (Organization) `GET /api/incidents?organizationId=:organizationId` Lists incidents for an organization (scoped by your permissions). ## Reports ### Download PDF Report `GET /api/websites/:websitePublicId/report.pdf?period=last-week|last-month|last-quarter&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD` Downloads a generated PDF report for a website. ## Uptime badge Every website has a public SVG badge showing its uptime for the last 24 hours, 7 days or 30 days. It needs no authentication and is addressed by the website's `publicId` **only**; the integer id is not accepted (it answers `404`). ``` https://uptimeify.io/api/public/badge/?period=30d ``` | Parameter | Values | Default | |-----------|--------|---------| | `period` | `7d`, `30d`; any other value or none means the last 24 hours | last 24 hours | The response is `image/svg+xml`, cached for five minutes. Embed it as `` in Markdown or as an `` tag; the badge URL is also shown on the website's detail page. ## Endpoints - [Get Uptime Stats](/api/monitoring/get-uptime-stats) - [Get Check History](/api/monitoring/get-check-history) - [Get Incident History](/api/monitoring/get-incident-history) - [Get Alert History](/api/monitoring/get-alert-history) - [Get Monitoring Data](/api/monitoring/get-monitoring-data) - [List Incidents (Organization)](/api/monitoring/list-incidents) - [Get Incident Details](/api/monitoring/get-incident-details) - [Download PDF Report](/api/monitoring/download-report-pdf)
### Monitoring Locations
URL: https://docs.uptimeify.io/api/monitoring-locations
Description: Retrieve the list of countries and locations where monitoring probes are available.
Summary: ## Endpoints - [List Countries](/api/monitoring-locations/list-countries): authenticated, grouped by country - [List Public Locations](/api/monitoring-locations/list-public-locations): public, unauthenticated ## Available Locations | Code | Name | Country | |------|------|---------| | `de-ber` | Berlin | Germany | | `de-fra` | Frankfurt | Germany | | `de-fsn` | Falkenstein | Germany | | `de-nbg` | Nuremberg | Germany | | `es-vit` | Logroño | Spain | | `fi-hel` | Helsinki | Finland | | `fr-par` | Paris | France | | `it-mil` | Milan | Italy | | `pl-waw` | Warsaw | Poland |
### List Countries with Locations
URL: https://docs.uptimeify.io/api/monitoring-locations/list-countries
Description: Returns countries that have monitoring locations with active workers. Requires authentication.
Summary: `GET /api/monitoring-locations/countries` ## Example (cURL) ```bash curl -X GET "$BASE_URL/api/monitoring-locations/countries" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "countries": [ { "code": "DE", "locations": 4, "workers": 23 }, { "code": "ES", "locations": 1, "workers": 4 }, { "code": "FI", "locations": 1, "workers": 6 }, { "code": "FR", "locations": 1, "workers": 4 }, { "code": "IT", "locations": 1, "workers": 4 }, { "code": "PL", "locations": 1, "workers": 6 } ] } ```
### List Public Monitoring Locations
URL: https://docs.uptimeify.io/api/monitoring-locations/list-public-locations
Description: Public endpoint (no authentication required) that returns all monitoring locations with active workers. Suitable for landing pages and marketing.
Summary: `GET /api/public/monitoring-locations` ## Example (cURL) ```bash curl -X GET "https://uptimeify.io/api/public/monitoring-locations" \ -H "Accept: application/json" ``` ## Response ```json { "locations": [ { "id": 19, "code": "de-ber", "name": "Berlin (DE)", "countryCode": "DE", "activeWorkers": 4 }, { "id": 18, "code": "de-fra", "name": "Frankfurt (DE)", "countryCode": "DE", "activeWorkers": 4 }, { "id": 8, "code": "de-fsn", "name": "Falkenstein (DE)", "countryCode": "DE", "activeWorkers": 6 }, { "id": 7, "code": "de-nbg", "name": "Nuremberg (DE)", "countryCode": "DE", "activeWorkers": 7 }, { "id": 20, "code": "es-vit", "name": "Logroño (ES)", "countryCode": "ES", "activeWorkers": 4 }, { "id": 3, "code": "fi-hel", "name": "Helsinki (FI)", "countryCode": "FI", "activeWorkers": 6 }, { "id": 17, "code": "fr-par", "name": "Paris (FR)", "countryCode": "FR", "activeWorkers": 4 }, { "id": 6, "code": "it-mil", "name": "Milan (IT)", "countryCode": "IT", "activeWorkers": 4 }, { "id": 5, "code": "pl-waw", "name": "Warsaw (PL)", "countryCode": "PL", "activeWorkers": 6 } ] } ``` `activeWorkers` is a live value and varies over time.
### Backfill Incident
URL: https://docs.uptimeify.io/api/monitoring/backfill-incident
Description: Records a past, already resolved incident with its real times on status pages, without notifying anyone.
Summary: `POST /api/incidents/backfill` Records an incident that is already over, like "Backfill incident" on Atlassian Statuspage: an outage you handled without the status page, or before it existed. You give the real start and end and, optionally, timeline updates with their own times. The incident is created resolved and appears on the named status pages: - in the incident history of every layout, with its updates, - in the uptime bars of the affected **manual** components (layout `statusboard`), when its impact is `partial_outage` or `major_outage` (`degraded` and `maintenance` do not count as downtime). Monitor components keep the bars measured by their monitor. It is recorded **silently**: no email, webhook, Slack or Teams notification, and no entry in the RSS/Atom feed, regardless of the pages' subscription settings. Later changes follow the normal endpoints (for example [Post Incident Update](/api/monitoring/post-incident-update) with its own `notifySubscribers`). This is what "Backfill incident" in the status pages module and the MCP tool `backfill_incident` do. Not idempotent: a repeated call records a second incident. ## Authentication Without status pages: role `admin` or `editor` (or an organization API token). With status pages, each page in `statusPageIds` decides: organization-wide callers need the role `admin` or `editor`; customer-bound users (also with the role `readonly`) and customer-bound API tokens need `self_service` pages, or `managed` pages with the customer's `canEditManaged` exception (otherwise `403 managed_by_organization`). Every page in `statusPageIds` must belong to your organization (otherwise `404 statusPageNotFound`) and be within your customer scope; without `customerId` the incident belongs to the organization, so a customer-scoped login or token gets `403 forbidden`. Needs the status pages module (`403 statusPagesModuleDisabled`). - Header: `Authorization: Bearer ` ## Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `title` | string | yes | Headline, 1 to 200 characters. | | `severity` | string | yes | `minor`, `major`, `critical` or `maintenance`. | | `startedAt` | string | yes | ISO 8601 start, in the past. | | `resolvedAt` | string | yes | ISO 8601 end, in the past and after `startedAt`. | | `statusPageIds` | array | yes | Status pages (id or publicId), 1 to 10. A page without one of `componentIds` gets the incident page-wide. | | `componentIds` | array | no | Affected components (id or publicId), at most 100; each must belong to one of `statusPageIds`. | | `impact` | string | no | `degraded`, `partial_outage`, `major_outage` or `maintenance`. Default from `severity` as in [Create Manual Incident](/api/monitoring/create-manual-incident). | | `componentImpacts` | array | no | Impact of single components, `[{ "componentId": 8, "impact": "major_outage" }]`; each must also be in `componentIds`. | | `customerId` | integer | no | Customer the incident belongs to. With it, only pages without a customer or of that customer. | | `summary` | string | no | Up to 5,000 characters. | | `updates` | array | no | Up to 50 timeline updates `{ "status", "body", "createdAt" }`: `status` is `investigating`, `identified`, `monitoring` or `resolved`, `body` 1 to 5,000 characters, `createdAt` an ISO 8601 time between `startedAt` and `resolvedAt`. | **Time rules:** `startedAt` must be before `resolvedAt` and every update time between them (`400 invalidDateRange`); no time may be in the future (`400 backfillInFuture`); `startedAt` may be at most 90 days before the oldest of the named pages was created, the span the uptime bars cover (`400 backfillTooOld`). Unknown fields are rejected with `400 invalidRequestBody`. ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/incidents/backfill" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Payments failed", "severity": "major", "startedAt": "2026-10-20T08:10:00Z", "resolvedAt…
### Create Manual Incident
URL: https://docs.uptimeify.io/api/monitoring/create-manual-incident
Description: Creates a manual incident on a customer's status pages or on chosen status pages and components.
Summary: `POST /api/incidents` Creates a **manual** incident: an announcement on status pages, written by you rather than detected by a monitor. With `customerId` it appears on every status page of that customer, as before. Since 27 October 2026 `customerId` is optional: with `statusPageIds` the incident appears on those pages, page-wide or on the components in `componentIds`, also on a page without a customer or without a single monitor. Subscribers of every page the incident appears on are notified. The notification carries the text of the first update (`updateBody`). ## Authentication Without status pages: role `admin` or `editor` (or an organization API token). With status pages, each page in `statusPageIds` decides: organization-wide callers need the role `admin` or `editor`; customer-bound users (also with the role `readonly`) and customer-bound API tokens need `self_service` pages, or `managed` pages with the customer's `canEditManaged` exception (otherwise `403 managed_by_organization`). Without `customerId` the incident belongs to the organization, like a status page without a customer: a customer-scoped login or token gets `403 forbidden`. Every page in `statusPageIds` must belong to your organization (otherwise `404 statusPageNotFound`) and be within your customer scope. - Header: `Authorization: Bearer ` ## Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `customerId` | integer | No* | Customer whose status pages show the incident. *Either `customerId` or `statusPageIds` is required. | | `websiteId` | integer | No | A website of `customerId` the incident is about. Needs `customerId`. | | `title` | string | Yes | Headline, 1 to 200 characters. | | `severity` | string | Yes | `minor`, `major`, `critical` or `maintenance`. | | `summary` | string | No | Up to 5,000 characters. | | `startedAt` | string | No | ISO 8601 time, default now. | | `updateStatus` | string | No | First timeline update together with `updateBody`: `investigating`, `identified`, `monitoring` or `resolved` (opens the incident resolved). | | `updateBody` | string | No | Text of the first update, up to 5,000 characters. | | `statusPageIds` | array | No* | Status pages (id or publicId), at most 10. A page without one of `componentIds` gets the incident page-wide. With `customerId`, only pages without a customer or of that customer. | | `componentIds` | array | No | Affected components (id or publicId), at most 100; each must belong to one of `statusPageIds`. While the incident is open, these manual components take its `impact`. | | `impact` | string | No | `degraded`, `partial_outage`, `major_outage` or `maintenance`. Default from `severity`: `minor` = `degraded`, `major` = `partial_outage`, `critical` = `major_outage`, `maintenance` = `maintenance`. | | `componentImpacts` | array | No | Impact of single components, `[{ "componentId": 8, "impact": "major_outage" }]`, overriding `impact` for them. Each `componentId` must also be in `componentIds` (same spelling), otherwise `400 invalidRequestBody`. | | `notifySubscribers` | boolean | No | Default `true`. `false` puts the incident on the pages (history, RSS feed) without email or webhook notifications to their subscribers. | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/incidents" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Card payments failing", "severity": "major", "statusPageIds": ["2b9c7d1e-5f3a-4c8b-9e0d-1a2b3c4d5e6f"], "componentIds": [8], "updateStatus": "investigating", "updateBody": "We are looking into failed card payments." }' ``` ## Response `201 Created` ```json { "incident": { "id": 5121, "publicId": "8d1f0c2e-6a2b-4f1e-9b7c-2e5a1d3c4b5a" } } ``` ## Common Errors - `400 Bad Request` (`incidentTargetRequired`) when neither `customerId` nor `statusPageIds` is given - `400 Bad Request` (`statusPageIdsRequired`) when `componentIds` is given without `statusPageIds` - `400 Bad Request` (`statu…
### Delete Incident (Manual only)
URL: https://docs.uptimeify.io/api/monitoring/delete-incident
Description: Deletes a manually created (status-page) incident. Monitor-generated incidents cannot be deleted.
Summary: `DELETE /api/incidents/:id` Deletes a **manual** incident (a status-page announcement created by an admin) together with its timeline updates. Monitor-generated incidents are worker-owned and can never be deleted, the endpoint rejects them with `403 notManualIncident`. ## Authentication Within the incident's customer scope. If the incident is linked to status pages, every linked page must allow it: organization-wide callers need the role `admin` or `editor`; customer-bound users (also with the role `readonly`) and customer-bound API tokens need `self_service` pages, or `managed` pages with the customer's `canEditManaged` exception (otherwise `403 managed_by_organization`). An incident linked to no page keeps the role rule: `admin` or `editor`. - Header: `Authorization: Bearer ` ## Path Parameters - `id` (required): The incident's numeric ID or its `publicId` (UUID). ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X DELETE "$BASE_URL/api/incidents/8d1f0c2e-6a2b-4f1e-9b7c-2e5a1d3c4b5a" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "success": true, "ok": true } ``` `ok` is deprecated and stays for existing readers; read `success`. ## Common Errors - `400 Incident id is required` if no ID is supplied - `400 Invalid Incident identifier` if the ID is neither a numeric incident id nor a UUID - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have write access to the incident's customer - `403 Forbidden` (`managed_by_organization`) when you are customer-bound (user, also with the role `readonly`, or token) and a status page involved is `managed` without the customer's `canEditManaged` exception - `403 Only manual incidents can be deleted` (`data.code: notManualIncident`) if the incident is monitor-generated - `404 Incident not found` if no incident matches the ID
### Download PDF Report
URL: https://docs.uptimeify.io/api/monitoring/download-report-pdf
Description: Downloads a PDF report for a website.
Summary: `GET /api/websites/:websitePublicId/report.pdf` ## Query Parameters You can either use a predefined `period` or a custom date range. - `period` (optional, default: `last-month`): `last-week`, `last-month`, `last-quarter` - `startDate` / `endDate` (optional): `YYYY-MM-DD` If `startDate` and `endDate` are provided, they take precedence. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -L "$BASE_URL/api/websites/6bfec6f6-245a-47ce-843b-157d97d56f88/report.pdf?period=last-month" \ -H "Authorization: Bearer $TOKEN" \ -o report.pdf ``` ## Response The response is a PDF (`application/pdf`). ## Common Errors - `400 Website public ID (UUID) required` if `:websitePublicId` is invalid - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the website - `404 Website not found` if the website does not exist
### Get Alert History
URL: https://docs.uptimeify.io/api/monitoring/get-alert-history
Description: Returns notification/escalation attempts (alert history) for incidents of a website.
Summary: `GET /api/websites/:websitePublicId/alert-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `websitePublicId` (Path, required): Website public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). - `limit` (number, optional): Items per page (default: `25`; max `100`). Ignored in favor of export defaults when `format=csv` or `download=1` (default `10000`, max `50000`). - `status` (string, optional): `sent` or `failed`. - `from` / `to` (ISO date string, optional): Filter by `sentAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` to force an attachment download, `0` (default) for the page. - `envelope` (string, optional): `items` answers as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/websites/11111111-1111-4111-8111-111111111111/alert-history?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [ { "id": 987, "incidentId": 123, "type": "slack", "status": "sent", "channelName": "Ops Slack", "channelType": "slack", "channelConfig": null, "sentAt": "2026-02-26T12:11:00.000Z", "errorMessage": null } ], "total": 1, "page": 1, "perPage": 25 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }` (`perPage` is the `limit`). Without it the endpoint still answers the current form `{ data, total, page, pageCount }`, which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. Each entry is one delivery attempt to one notification channel. `status` is `sent` or `failed` (with `errorMessage` set on failure); `channelType` is the channel type (e.g. `email`, `slack`, `opsgenie`). `channelConfig` has secrets redacted. When `format=csv` (or `download=1`), the response is a `text/csv` (or `application/json` for `format=json&download=1`) attachment instead of the paginated JSON list above. ## Common Errors - `400 Website public ID (UUID) required` if `:websitePublicId` is invalid - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the monitor
### Get Check History
URL: https://docs.uptimeify.io/api/monitoring/get-check-history
Description: Returns the latest monitoring checks for a website.
Summary: `GET /api/websites/:websitePublicId/check-history` ## Query Parameters - `limit` (optional, default: `50`, max: `200`) - `checkType` (optional, supports values such as `http_status`, `ssl_check`, `combined`, `playwright`, `heartbeat`, `dns`, plus legacy values like `http` and `ssl`) ## Path Parameters - `websitePublicId` (recommended): website public UUID - Backward compatibility: legacy numeric website IDs are still accepted ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/websites/6bfec6f6-245a-47ce-843b-157d97d56f88/check-history?limit=25&checkType=dns" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "data": [ { "id": "chk_01H...", "status": "success", "errorMessage": null, "warningMessage": null, "timingDns": 12, "diagnostics": null, "checkedAt": "2026-02-26T12:34:56.000Z", "locationId": 7, "locationName": "Nuremberg (DE)", "locationCode": "de-nbg" } ] } ``` ## Common Errors - `400 Invalid Website identifier` if `:websitePublicId` is neither a valid UUID nor a legacy numeric ID - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status`, `minMs` or `maxMs` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `400 Invalid checkType` if you send an unsupported `checkType` - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the website
### Get Incident Details
URL: https://docs.uptimeify.io/api/monitoring/get-incident-details
Description: Returns detailed incident data, including a timeline of failed/recovery checks and alert events.
Summary: `GET /api/incidents/:incidentPublicId` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `incidentPublicId` (Path, required): Incident public UUID. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/incidents/6bfec6f6-245a-47ce-843b-157d97d56f88" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` Note: `evidenceCheck` can be `null`. `screenshotUrl` is only set when `hasScreenshot` is `true`. ## Timeline resolution `timeline.outageChecks` lists every check between the confirmation (`confirmationAt`, exclusive) and the end of the incident, failed and successful alike, ascending and capped at 200; `outageChecksTotal` is the full count. Read `status` per entry: an aggregated bucket is `failure` as soon as one location failed in it. Every entry in `outageStartedCheck`, `failedChecks`, `outageChecks` and `recoveryChecks` carries a `resolution`: - `raw`: a single check at a single location. `location`, `statusCode` and `errorMessage` are the ones that location reported. - `1min`: one minute of the monitoring aggregate, used once an incident is older than the raw check retention window (24 hours). `location`, `statusCode` and `errorMessage` are `null`, `responseTimeMs` is the average over the minute, and two extra fields say how many locations were behind it: `totalLocations` and `failedLocations`. - `15min` and `1day`: one 15-minute or one daily bucket, used once the minute aggregate no longer reaches back (7 days for `15min`, 30 days for `1day`). Same `null` fields as `1min`, but the counts are single location checks, not locations: `totalChecks` and `failedChecks`. - Server and DNS monitors (TCP, SSH, FTP, SMTP, IMAP/POP, ICMP, DNS) have no 15-minute tier: `1min` reaches back 30 days, older incidents get `1day` entries with `totalChecks` and `failedChecks`. The `id` of an aggregated entry is synthetic (`-`, e.g. `1min-2026-09-01T10:00:00.000Z`) and cannot be looked up as a check. The four lists are resolved independently, so an incident that spans a boundary can mix resolutions. ## Example Response (excerpt) ```json { "incident": { "id": 123, "websiteId": 101, "type": "downtime", "status": "open", "startedAt": "2026-02-26T12:10:00.000Z", "resolvedAt": null, "statusCode": null, "errorMessage": "Timeout", "responseTimeMs": null, "falseAlarmAt": null, "falseAlarmReason": null, "publicTitle": null, "publicStatus": "open", "publicResolvedAt": null }, "timeline": { "outageStartedAt": "2026-02-26T12:08:00.000Z", "outageStartedCheck": { "id": "chk_01H...", "checkedAt": "2026-02-26T12:08:00.000Z", "status": "failure", "statusCode": 503, "errorMessage": "Timeout", "responseTimeMs": null, "location": { "id": 7, "code": "de-nbg", "name": "Nuremberg (DE)" }, "resolution": "raw" }, "confirmationAt": "2026-02-26T12:10:00.000Z", "failedChecks": [ { "id": "1min-2026-02-26T12:09:00.000Z", "checkedAt": "2026-02-26T12:09:00.000Z", "status": "failure", "statusCode": null, "errorMessage": null, "responseTimeMs": 246, "location": null, "resolution": "1min", "totalLocations": 3, "failedLocations": 2 } ], "failedChecksTotal": 2, "alertEvents": [ { "id": 987, "sentAt": "2026-02-26T12:11:00.000Z", "type": "email", "status": "sent", "channelName": "Ops Email", "errorMessage": null } ], "recoveryChecks": [], "recoveryChecksTotal": 0, "outageChecks": [], "outageChecksTotal": 0 }, "evidenceCheck": { "id": "chk_01H...", "checkedAt": "2026-02-26T12:08:00.000Z", "diagnostics": null, "hasScreenshot": false, "screenshotUrl": null } } ``` ## False-alarm mark An incident can be marked as a false alarm (`POST /api/incidents/{id}/false-alarm`). Two read-only fields on `incident` report that mark: | Field | Type | Meaning | | --- | --- | --- | | `falseAlarmAt` | string \| null | When the mark was set, ISO 8601. `null` means the incident is not marked. | | `falseAlarmReason` | string \| null | The free-text reason given…
### Get Incident History
URL: https://docs.uptimeify.io/api/monitoring/get-incident-history
Description: Returns incidents for a single website (latest 100), including a computed duration.
Summary: `GET /api/websites/:websitePublicId/incident-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `websitePublicId` (Path, required): Website public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). - `limit` (number, optional): Items per page (default: `25`; max `100`). Ignored in favor of export defaults when `format=csv` or `download=1` (default `10000`, max `50000`). - `status` (string, optional): `open`, `acknowledged`, or `resolved`. - `type` (string, optional): `downtime`, `http_status`, `ssl_expiry`, `ssl_critical`, `ssl_warning`, `response_time`, `dnsbl`, `domain_expiry_warning`, `critical`, or `inconclusive`. - `from` / `to` (ISO date string, optional): Filter by `startedAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` to force an attachment download, `0` (default) for the page. - `envelope` (string, optional): `items` answers as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/websites/11111111-1111-4111-8111-111111111111/incident-history?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [ { "id": 123, "publicId": "55555555-5555-4555-8555-555555555555", "type": "downtime", "status": "resolved", "startedAt": "2026-02-26T12:10:00.000Z", "endedAt": "2026-02-26T12:12:30.000Z", "durationMs": 150000, "statusCode": null, "errorMessage": "connect ETIMEDOUT", "details": "connect ETIMEDOUT", "isOngoing": false } ], "total": 1, "page": 1, "perPage": 25 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }` (`perPage` is the `limit`). Without it the endpoint still answers the current form `{ data, total, page, pageCount }`, which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. **Deprecated field:** `duration` (text, e.g. `2m 30s`) is still sent next to `durationMs` until it is removed on 2027-01-18. Read `durationMs`. `status` is `open`, `acknowledged`, or `resolved`. Ongoing incidents have a `null` `endedAt` and `isOngoing: true`. When `format=csv` (or `download=1`), the response is a `text/csv` (or `application/json` for `format=json&download=1`) attachment instead of the paginated JSON list above. ## Common Errors - `400 Website public ID (UUID) required` if `:websitePublicId` is invalid - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status` or `type` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the monitor
### Get Monitoring Data
URL: https://docs.uptimeify.io/api/monitoring/get-monitoring-data
Description: Returns time series data used for charts (response times, status tracker, uptime percentage).
Summary: `GET /api/websites/:id/monitoring-data` To keep responses small, the endpoint down-samples the returned data points if needed. ## Query Parameters - `range` (optional, default: `day`): `day`, `week`, `month`, `year` - `maxPoints` (optional, default: `300`, max: `2000`): Limits the number of returned data points. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/websites/6bfec6f6-245a-47ce-843b-157d97d56f88/monitoring-data?range=week" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response (excerpt) ```json { "responseTimeData": [ { "timestamp": "2026-02-26T12:00:00.000Z", "responseTime": 123, "status": "success", "success": true, "timingDns": 12, "timingTcp": 20, "timingTls": 30, "timingTtfb": 50, "timingTransfer": 11 } ], "statusData": [ { "date": "26.02", "status": "online" } ], "uptimePercentage": "99.95", "checkSuccessRatePercentage": "99.80", "totalChecks": 100, "successfulChecks": 99 } ``` ## Data retention The series is read from the finest aggregate that still covers the requested range: minute data for the last 7 days, 15-minute buckets up to 30 days back and daily buckets beyond that. In the coarser buckets `timingDns`, `timingTcp`, `timingTls`, `timingTtfb` and `timingTransfer` are reported as `0` (not measured), and `successRate` is the share of successful location checks rather than the per-minute quorum. ## Common Errors - `400 Website public ID (UUID) required` if `:websitePublicId` is invalid - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the website - `500 Failed to fetch monitoring data` on server errors
### Get Uptime Stats
URL: https://docs.uptimeify.io/api/monitoring/get-uptime-stats
Description: Returns uptime percentages and average response times for the last day, month and year.
Summary: `GET /api/websites/:websitePublicId/uptime-stats` ## Path Parameters - `websitePublicId` (recommended): website public UUID - Backward compatibility: legacy numeric website IDs are still accepted ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/websites/9a3d4d4d-7a4b-4f37-a9df-2a6f6d9d7a10/uptime-stats" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "day": "100.00", "month": "99.95", "year": "99.90", "dayAvgResponse": 125, "monthAvgResponse": 118, "yearAvgResponse": 120, "blockedRatio": { "day": 0, "month": 0.02, "year": 0 } } ``` ## Response Fields - `day`, `month`, `year`: uptime percentage as a string with two decimals, or `null` when nothing was measurable in that period. - `blockedRatio`: share of the period we could not measure, between `0` and `1`, `null` for an empty period. A site's bot protection can answer our check with a challenge instead of the page; that time leaves the uptime calculation, so it counts neither as up nor as down, and `day`/`month`/`year` are the remaining, measured time. ## Common Errors - `400 Invalid Website identifier` if `:websitePublicId` is neither a valid UUID nor a legacy numeric ID - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the website
### List Incidents (Organization)
URL: https://docs.uptimeify.io/api/monitoring/list-incidents
Description: Lists incidents for an organization. If organizationId is omitted, the API falls back to the organization from your session.
Summary: `GET /api/incidents` Readonly users only see incidents for customers they are assigned to. ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Query Parameters - `organizationId` (optional): Organization ID. Defaults to your session organization. - `source` (optional): Filter by incident source. `manual` returns status-page announcements created by an admin; `monitor` returns incidents generated automatically by the monitoring workers. Any other value is ignored and all sources are returned. Useful because manual incidents can be far older than the newest monitor incidents and would otherwise fall outside the `limit` window. - `limit` (optional, default: `100`, max: `500`): Maximum number of incidents to return. - `offset` (optional, default: `0`): Pagination offset. - `includeTotal` (optional, default: `0`): If set to `1` (or `true`), the response includes `total`, `limit`, and `offset`. - `onStatusPage` (optional): `true` or `1` returns only incidents a status page shows as an incident: manual ones and those linked to a status page. Other values than `true`, `false`, `1`, `0` answer `400`. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/incidents?organizationId=1" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` To paginate: ```bash curl -X GET "$BASE_URL/api/incidents?organizationId=1&limit=100&offset=0" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` To list only manually created (status-page) incidents: ```bash curl -X GET "$BASE_URL/api/incidents?organizationId=1&source=manual" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response (excerpt) ```json [ { "id": 123, "websiteId": 101, "status": "open", "severity": "downtime", "startedAt": "2026-02-26T12:10:00.000Z", "resolvedAt": null, "lastNotifiedAt": "2026-02-26T12:11:00.000Z", "errorMessage": "Timeout", "statusCode": null, "responseTimeMs": null, "website": { "id": 101, "name": "Main Marketing Site", "url": "https://deinkunde.com", "status": "active" }, "customer": { "id": 12, "email": "ops@deinkunde.com", "company": "Acme Corp" } } ] ``` If `includeTotal=1`, the response shape changes to: ```json { "incidents": [], "total": 1234, "limit": 100, "offset": 0 } ``` **`statusPages`** (since 28 October 2026): every entry carries `[{ "id", "publicId", "name" }]`, the status pages the incident is shown on as an incident: linked pages, and for a manual incident with a customer the pages of that customer. Empty for a monitor incident that is not linked. **`publicTitle`, `publicStatus`, `publicResolvedAt`** (since 28 October 2026): the incident as status pages show it. `publicTitle` is the title set for the pages or `null` (the pages then show `title`). `publicStatus` is `open` or `resolved`; for a monitor incident timeline updates set it independently of `status`, otherwise it follows `status`. `publicResolvedAt` is when it was resolved on the pages. **Deprecated fields:** `started_at`, `resolved_at`, `last_notified_at`, `error_message`, `status_code` and `response_time_ms` are still sent next to `startedAt`, `resolvedAt`, `lastNotifiedAt`, `errorMessage`, `statusCode` and `responseTimeMs` until they are removed on 2027-01-18, with and without `includeTotal`. Read the camelCase fields. ### Manual incidents without a customer Since 27 October 2026 a manual incident can be created without a customer, linked to status pages only. The list includes it for organization-wide roles and tokens with `customer: null`; a customer-scoped login or token does not see it. ## Common Errors - `400 Organization ID is required` if the API cannot infer an organization - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the organization - `500 Failed to fetch incidents` on unexpected errors
### Post Incident Update
URL: https://docs.uptimeify.io/api/monitoring/post-incident-update
Description: Posts a public update to the timeline of a manual or monitor incident and notifies status page subscribers.
Summary: `POST /api/incidents/:id/updates` Posts a timeline update to an incident: the text appears on every status page the incident is shown on and goes to the subscribers of those pages. This is what "Post update" in the status pages module and the MCP tool `post_incident_update` do. What the update's `status` changes depends on the incident (since 28 October 2026): - **Manual incident:** the incident follows the update. `resolved` resolves it (`status` and `resolvedAt`) and sends the all-clear; any other status on a resolved incident reopens it and notifies subscribers again. - **Monitor incident:** only the public status changes (`publicStatus`, `publicResolvedAt`). `resolved` resolves it on the status pages and sends the all-clear there; any other status reopens it there. The monitoring incident stays as it is: its `status` and `resolvedAt` follow the monitor checks, not the update. While the incident is still open on the pages, a recovering monitor sends no all-clear. The all-clear and the reopen notice are sent only on a real change of the public status. A second `resolved` update on an incident that is already resolved on the pages is posted, but sends no second all-clear. **Repeats:** a call with the same `status` and `body` as an update the incident already has creates nothing new. It answers `200 OK` with the existing update and `deduplicated: true`, and sends nothing again. Repeat a call whose response did not arrive without risk. To change the internal status, title or links instead, use [Update Incident](/api/monitoring/update-incident). [Get Incident Details](/api/monitoring/get-incident-details) returns `publicStatus` and `publicResolvedAt`. ## Authentication Within the incident's customer scope. If the incident is linked to status pages, every linked page must allow it: organization-wide callers need the role `admin` or `editor`; customer-bound users (also with the role `readonly`) and customer-bound API tokens need `self_service` pages, or `managed` pages with the customer's `canEditManaged` exception (otherwise `403 managed_by_organization`). An incident linked to no page keeps the role rule: `admin` or `editor`. An incident without a customer needs an organization-wide role or token; for any other organization it answers `404 incidentNotFound`. Organization-wide `readonly` gets `403 forbidden`. - Header: `Authorization: Bearer ` ## Path Parameters - `id` (required): numeric id or `publicId` (UUID). ## Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `status` | string | yes | `investigating`, `identified`, `monitoring` or `resolved`. | | `body` | string | yes | The update text, 1 to 5,000 characters after trimming. | | `notifySubscribers` | boolean | no | Default `true`. `false` records the update in the feed and history of the pages without email or webhook notifications; this also applies to the all-clear or reopen notice it triggers. | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/incidents/5121/updates" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "identified", "body": "The cause is a faulty database node. We are switching to the replica." }' ``` ## Response `201 Created` for a new update, `200 OK` for a repeat. ```json { "update": { "id": 8812, "publicId": "3f6c2a8e-6b1d-4c39-9a57-2d0e5b7c1f44", "status": "identified", "body": "The cause is a faulty database node. We are switching to the replica.", "createdAt": "2026-10-28T09:41:12.000Z" }, "deduplicated": false } ``` | Field | Description | |-------|-------------| | `update` | The posted update, or for a repeat the existing one. | | `deduplicated` | `true` when the same `status` and `body` was already posted; nothing was created or sent. | ## Common Errors - `400 Bad Request` (`invalidRequestBody`) when `status` is missing or not one of the four values, or `body` is empty or longer than 5,000 characters - `400 Bad Request` (`incidentNoCustomer`) when…
### Publish Postmortem
URL: https://docs.uptimeify.io/api/monitoring/publish-postmortem
Description: Publishes the postmortem of a resolved incident on its status pages, optionally with one notification to their subscribers.
Summary: `POST /api/incidents/:id/postmortem/publish` Publishes the postmortem of an incident. It then appears under the incident on every status page the incident is shown on, in every layout, as an expandable section. This is what "Publish" in the postmortem card of the status pages module and the MCP tool `publish_postmortem` do. - Only a **resolved** incident can get a published postmortem: resolved on the status pages (`publicStatus`, see [Get Incident Details](/api/monitoring/get-incident-details)). Otherwise the call answers `409 postmortemIncidentNotResolved`. - With `body` the text is saved first, in the same call. Without it the text saved with [Save Postmortem](/api/monitoring/save-postmortem) is published; without a saved text the call answers `404 postmortemNotFound`. - With `notifySubscribers: true` the subscribers of those pages get one notification `postmortem_published` (email, webhook, Slack, Teams), after the page's subscription delay. If the postmortem is unpublished before that, nothing is sent. - **Repeats:** an already published postmortem stays published and answers `200 OK`. A `body` replaces its text; no second notification is sent. ## Authentication Within the incident's customer scope. If the incident is linked to status pages, every linked page must allow it: organization-wide callers need the role `admin` or `editor`; customer-bound users (also with the role `readonly`) and customer-bound API tokens need `self_service` pages, or `managed` pages with the customer's `canEditManaged` exception (otherwise `403 managed_by_organization`). An incident linked to no page keeps the role rule: `admin` or `editor`. An incident without a customer needs an organization-wide role or token; for any other organization it answers `404 incidentNotFound`. Organization-wide `readonly` gets `403 forbidden`. - Header: `Authorization: Bearer ` ## Path Parameters - `id` (required): numeric id or `publicId` (UUID) of the incident. ## Request Body Optional; an empty body publishes the saved text without notification. | Field | Type | Required | Description | |-------|------|----------|-------------| | `body` | string | no | Markdown, 1 to 50,000 characters. Saved before publishing. | | `notifySubscribers` | boolean | no | Default `false`. `true` notifies the subscribers of the pages once. | Unknown fields are rejected with `400 invalidRequestBody`. ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/incidents/5121/postmortem/publish" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "notifySubscribers": true }' ``` ## Response `200 OK` ```json { "incidentId": 5121, "incidentPublicId": "8a3c1f6e-2b7d-4e59-9c1a-5d2e7f0b4c33", "body": "## Cause\nA database node ran out of disk space.", "publishedAt": "2026-10-28T14:05:40.000Z", "updatedAt": "2026-10-28T14:02:11.000Z" } ``` On the public status page ([Get Public Status Page](/api/status-pages/get-public-status-page)) the incident then carries `postmortem: { body, publishedAt }`. To take it down again, use [Unpublish Postmortem](/api/monitoring/unpublish-postmortem). ## Common Errors - `400 Bad Request` (`invalidRequestBody`) when `body` is empty or longer than 50,000 characters, a field has the wrong type, or an unknown field is sent - `401 Unauthorized` when not authenticated - `403 Forbidden` (`forbidden`) when your role or customer scope does not allow it - `403 Forbidden` (`managed_by_organization`) when you are customer-bound (user, also with the role `readonly`, or token) and a status page involved is `managed` without the customer's `canEditManaged` exception - `404 Not Found` (`incidentNotFound`) when the incident does not exist in your organization - `404 Not Found` (`postmortemNotFound`) when no text was saved and no `body` was sent - `409 Conflict` (`postmortemIncidentNotResolved`) when the incident is not resolved on the status pages
### Save Postmortem
URL: https://docs.uptimeify.io/api/monitoring/save-postmortem
Description: Saves the public postmortem (Markdown) of an incident as a draft, or replaces the text of a published one.
Summary: `PUT /api/incidents/:id/postmortem` Saves the public postmortem of an incident: what happened, why, and what was changed, written in Markdown. Like on Atlassian Statuspage, the postmortem is shown under the incident on every status page the incident appears on, once it is published with [Publish Postmortem](/api/monitoring/publish-postmortem). Until then it is a draft, visible only in the status pages module. An incident has at most one postmortem; this call creates it or replaces its text. On a published postmortem the new text goes live immediately and it stays published. Saving sends no notification. The text can be saved at any time, publishing needs a resolved incident. The status pages render the Markdown themselves and never as raw HTML: headings, paragraphs, lists, **bold**, *italic*, `code` and links to `http(s)` addresses. Anything else, including HTML tags, is shown as plain text. ## Authentication Within the incident's customer scope. If the incident is linked to status pages, every linked page must allow it: organization-wide callers need the role `admin` or `editor`; customer-bound users (also with the role `readonly`) and customer-bound API tokens need `self_service` pages, or `managed` pages with the customer's `canEditManaged` exception (otherwise `403 managed_by_organization`). An incident linked to no page keeps the role rule: `admin` or `editor`. An incident without a customer needs an organization-wide role or token; for any other organization it answers `404 incidentNotFound`. Organization-wide `readonly` gets `403 forbidden`. - Header: `Authorization: Bearer ` ## Path Parameters - `id` (required): numeric id or `publicId` (UUID) of the incident. ## Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `body` | string | yes | Markdown, 1 to 50,000 characters after trimming. | Unknown fields are rejected with `400 invalidRequestBody`. ## Example (cURL) ```bash curl -X PUT "$BASE_URL/api/incidents/5121/postmortem" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "body": "## Cause\nA database node ran out of disk space.\n\n## Actions\n- Alert at 80 % disk usage" }' ``` ## Response `200 OK` ```json { "incidentId": 5121, "incidentPublicId": "8a3c1f6e-2b7d-4e59-9c1a-5d2e7f0b4c33", "body": "## Cause\nA database node ran out of disk space.\n\n## Actions\n- Alert at 80 % disk usage", "publishedAt": null, "updatedAt": "2026-10-28T14:02:11.000Z" } ``` | Field | Description | |-------|-------------| | `publishedAt` | `null` = draft; otherwise when it was published (ISO 8601). | | `updatedAt` | When the text was last saved. | [Get Incident Details](/api/monitoring/get-incident-details) returns the same fields as `postmortem`. ## Common Errors - `400 Bad Request` (`invalidRequestBody`) when `body` is missing, empty, longer than 50,000 characters, or an unknown field is sent - `400 Bad Request` (`incidentNoCustomer`) when the incident has neither a customer nor a status page - `401 Unauthorized` when not authenticated - `403 Forbidden` (`forbidden`) when your role or customer scope does not allow it - `403 Forbidden` (`managed_by_organization`) when you are customer-bound (user, also with the role `readonly`, or token) and a status page involved is `managed` without the customer's `canEditManaged` exception - `404 Not Found` (`incidentNotFound`) when the incident does not exist in your organization
### Unpublish Postmortem
URL: https://docs.uptimeify.io/api/monitoring/unpublish-postmortem
Description: Takes a published postmortem off the status pages; the text stays as a draft.
Summary: `DELETE /api/incidents/:id/postmortem/publish` Takes the postmortem of an incident off its status pages. The text is kept as a draft and can be published again with [Publish Postmortem](/api/monitoring/publish-postmortem). A `postmortem_published` notification that has not been delivered yet (subscription delay) is not sent. ## Authentication Within the incident's customer scope. If the incident is linked to status pages, every linked page must allow it: organization-wide callers need the role `admin` or `editor`; customer-bound users (also with the role `readonly`) and customer-bound API tokens need `self_service` pages, or `managed` pages with the customer's `canEditManaged` exception (otherwise `403 managed_by_organization`). An incident linked to no page keeps the role rule: `admin` or `editor`. Organization-wide `readonly` gets `403 forbidden`. - Header: `Authorization: Bearer ` ## Path Parameters - `id` (required): numeric id or `publicId` (UUID) of the incident. ## Example (cURL) ```bash curl -X DELETE "$BASE_URL/api/incidents/5121/postmortem/publish" \ -H "Authorization: Bearer $TOKEN" ``` ## Response `204 No Content`, no body. ## Common Errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`forbidden`) when your role or customer scope does not allow it - `403 Forbidden` (`managed_by_organization`) when you are customer-bound (user, also with the role `readonly`, or token) and a status page involved is `managed` without the customer's `canEditManaged` exception - `404 Not Found` (`incidentNotFound`) when the incident does not exist in your organization - `404 Not Found` (`postmortemNotFound`) when the incident has no published postmortem (also on a second call)
### Update Incident
URL: https://docs.uptimeify.io/api/monitoring/update-incident
Description: Changes headline, severity, status and the linked status pages and components of an incident.
Summary: `PATCH /api/incidents/:id` Changes a manual or monitor incident: headline, summary, severity, status, and since 27 October 2026 the status pages and components it is linked to. Fields you leave out stay unchanged. Resolving (`status: resolved`) or reopening notifies subscribers of every page the incident appears on, including the linked ones. Since 28 October 2026, linking an open incident to a page it was not on yet (also a monitor incident) notifies the subscribers of that page once, with the text of the latest update; pages it was already on are not notified again. Since 28 October 2026 an incident on status pages has its own public title and its own public status, separate from the monitoring incident (as on Atlassian Statuspage). `publicTitle` sets the title the pages show; the internal `title` stays. For a monitor incident, a timeline update ([Post Incident Update](/api/monitoring/post-incident-update), "Post update" in the status pages module, `post_incident_update` over MCP) sets only the public status: `resolved` resolves it on the pages, any other status reopens it there, while the monitoring incident keeps its own `status` and `resolvedAt`. A monitor that recovers therefore sends no all-clear while the incident is still open on the pages. `status` on this endpoint stays the internal status; once a monitor incident has its own public status, changing `status` here notifies nobody. [Get Incident Details](/api/monitoring/get-incident-details) and [List Incidents](/api/monitoring/list-incidents) return `publicTitle`, `publicStatus` and `publicResolvedAt`. ## Authentication Within the incident's customer scope. If the incident is linked to status pages, every linked page must allow it: organization-wide callers need the role `admin` or `editor`; customer-bound users (also with the role `readonly`) and customer-bound API tokens need `self_service` pages, or `managed` pages with the customer's `canEditManaged` exception (otherwise `403 managed_by_organization`). An incident linked to no page keeps the role rule: `admin` or `editor`. Pages newly named in `statusPageIds` are checked the same way. An incident without a customer needs an organization-wide role or token; for any other organization it answers `404 incidentNotFound`. - Header: `Authorization: Bearer ` ## Path Parameters - `id` (required): numeric id or `publicId` (UUID). ## Request Body | Field | Type | Description | |-------|------|-------------| | `status` | string | `open`, `acknowledged` or `resolved`. | | `severity` | string | `minor`, `major`, `critical` or `maintenance`. | | `title` | string | 1 to 200 characters. | | `publicTitle` | string or null | Title on status pages, 1 to 200 characters; `null` shows `title` again. | | `summary` | string or null | Up to 5,000 characters, `null` clears it. | | `statusPageIds` | array | Replaces the linked pages (id or publicId). Same rules as on [Create Manual Incident](/api/monitoring/create-manual-incident). `[]` removes every link, which an incident without a customer cannot do (`400 incidentTargetRequired`). | | `componentIds` | array | Replaces the linked components, together with `statusPageIds`. | | `impact` | string | With `statusPageIds`: the impact of the new links. Alone: sets the impact of every existing link. | | `componentImpacts` | array | Together with `componentIds`: impact of single components, overriding `impact` for them, as on create. Without `componentIds` it answers `400 invalidRequestBody`. | | `notifySubscribers` | boolean | Default `true`. `false` records resolving, reopening or newly linked pages without email or webhook notifications. | ## Example (cURL) ```bash curl -X PATCH "$BASE_URL/api/incidents/5121" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "impact": "degraded" }' ``` ## Response `200 OK` ```json { "ok": true } ``` [Get Incident Details](/api/monitoring/get-incident-details) returns the links as `statusPageLinks`. ## Common Errors - `400…
### Monitors
URL: https://docs.uptimeify.io/api/monitors
Description: Manage protocol monitors (ICMP, SMTP, SSH, TCP, FTP, IMAP/POP).
Summary: Protocol monitor detail/update/delete/check endpoints use monitor-specific `publicId` UUIDs in the path. ## Resources - [ICMP Monitors](/api/monitors/icmp-monitors) - [SMTP Monitors](/api/monitors/smtp-monitors) - [SSH Monitors](/api/monitors/ssh-monitors) - [TCP Monitors](/api/monitors/tcp-monitors) - [FTP Monitors](/api/monitors/ftp-monitors) - [IMAP/POP Monitors](/api/monitors/imap-pop-monitors) - [DNS Monitors](/api/monitors/dns-monitors) - [DNSBL Monitoring (Customer IPs)](/api/monitors/dnsbl-monitoring) - [Domain Expiry Monitoring (Customer Domains)](/api/monitors/domain-expiry-monitoring)
### DNS Monitors
URL: https://docs.uptimeify.io/api/monitors/dns-monitors
Description: Manage DNS monitors that check DNS resolution/records for a hostname.
Summary: Path-based DNS monitor endpoints use `dnsMonitorPublicId` UUIDs. ## Endpoints - [List DNS Monitors](/api/monitors/dns-monitors/list-dns-monitors) - [Create DNS Monitor](/api/monitors/dns-monitors/create-dns-monitor) - [Get DNS Monitor](/api/monitors/dns-monitors/get-dns-monitor) - [Update DNS Monitor](/api/monitors/dns-monitors/update-dns-monitor) - [Delete DNS Monitor](/api/monitors/dns-monitors/delete-dns-monitor) - [Trigger DNS Check](/api/monitors/dns-monitors/trigger-check-dns-monitor) - [Get DNS Monitor Check History](/api/monitors/dns-monitors/get-dns-monitor-check-history)
### Create DNS Monitor
URL: https://docs.uptimeify.io/api/monitors/dns-monitors/create-dns-monitor
Description: Creates a new DNS monitor for a customer.
Summary: `POST /api/dns-monitors` ## Request Body ```json { "customerId": "6bfec6f6-245a-47ce-843b-157d97d56f88", "name": "Example DNS", "hostname": "deinkunde.com", "status": "active", "checkInterval": 30, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE", "FR"], "dnsConfig": { "rrtypes": ["A", "AAAA"], "matchMode": "exact", "expectedValues": { "A": ["93.184.216.34"], "AAAA": ["2606:2800:220:1:248:1893:25c8:1946"] }, "triggerOn": { "resolveError": true, "mismatch": true } } } ``` Notes: - `customerId`, `name`, `hostname`, `dnsConfig.rrtypes`, `dnsConfig.matchMode`, and `dnsConfig.expectedValues` are required. - `customerId` accepts either the internal numeric ID or the customer `publicId` UUID. - Global supporters cannot create DNS monitors. A readonly or customer-scoped login may create one inside its own customer scope; the monitor is then forced to `self_service` and refused with `selfServiceNotAllowed` or `selfServiceQuotaReached` when the package does not allow it or the quota is used up. - `hostname` must be a hostname (no protocol, no path). - `dnsConfig.expectedValues` must contain at least one expected value for every RR type listed in `dnsConfig.rrtypes`. - `allowedCheckCountryCodes` (string[], optional) - Restricts checks to these ISO-3166-1 alpha-2 country codes. - Each entry must be exactly two letters; entries are trimmed, upper-cased and deduplicated before they are stored. - Omit the key, send `null` or send an empty array to drop the restriction on the monitor; a restriction set on the customer itself still applies. - The two-letter rule checks the form only: a country code without an active check location is accepted, and the monitor then never runs a check. ### Duplicates If this customer already has a monitor with the same `hostname` (case and a trailing dot do not count) and the same set of record types in `dnsConfig.rrtypes`, the request is refused with `409` and `data.code` `monitorAlreadyExists`. `data.existingId` and `data.existingPublicId` name the existing monitor. Send `"allowDuplicate": true` to create the second monitor anyway (for example with a different interval or other alert channels). - `allowDuplicate` (boolean, optional, default `false`): create the monitor even if it is a duplicate. Not stored. ```json { "statusCode": 409, "statusMessage": "A monitor for this target already exists for this customer. Send allowDuplicate: true to create it anyway.", "data": { "code": "monitorAlreadyExists", "existingId": 300, "existingPublicId": "44444444-4444-4444-8444-444444444444" } } ``` ### Limit per target host An organization can have at most 100 monitors for the same target host, counted across all monitor types together (websites with HTTP, keyword, DNS website and Playwright with a real URL, plus TCP, ICMP, DNS, SSH, SMTP, FTP and IMAP/POP). The limit protects against the check fleet being misused as a load generator against third-party hosts. The exact hostname is compared: case, port, path and a trailing dot do not count, but `www.example.com` and `example.com` are different hosts. Once the limit is reached, the request is refused with `403` and `data.code` `targetHostMonitorLimitReached`. `data.host` names the normalized host, `data.limit` the limit. `"allowDuplicate": true` does not lift the limit. The same check runs when a PATCH changes the `hostname`. A PATCH that keeps the host always succeeds, and existing monitors above the limit stay in place. If you need a higher limit, contact support. Independently of your organization, at most 300 monitors across all Uptimeify customers may target the same host. Beyond that, the request is refused with `403` and `data.code` `targetHostPlatformLimitReached`; `data.host` and `data.limit` are set as above, and the message does not reveal how many monitors other organizations have. ```json { "statusCode": 403, "statusMessage": "Target host monitor limit reached: your organization already has 100 monitors for example.com (maximum 100 per host). Remove moni…
### Delete DNS Monitor
URL: https://docs.uptimeify.io/api/monitors/dns-monitors/delete-dns-monitor
Description: Deletes a DNS monitor.
Summary: `DELETE /api/dns-monitors/:dnsMonitorPublicId` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X DELETE \ "$BASE_URL/api/dns-monitors/11111111-1111-4111-8111-111111111111" \ -H "Authorization: Bearer $TOKEN" ``` ## Common errors - `401 Unauthorized` - `403 Forbidden` - `404 DNS monitor not found` ## Response Returns `204 No Content` on success. See [Error Codes](/api/error-codes-and-known-pitfalls) for error responses. ## Permissions Closed to the `readonly` role. A read-only login deletes no monitor, whatever its ownership class, and neither does an API token it issued: a token inherits the role of the user who created it. Editing a `self_service` monitor stays open to that role. A customer-scoped caller is bound by ownership class on top of that: a `managed` monitor is refused with `managed_by_organization` unless its customer carries `canEditManaged`.
### Get DNS Monitor
URL: https://docs.uptimeify.io/api/monitors/dns-monitors/get-dns-monitor
Description: Returns a single DNS monitor.
Summary: `GET /api/dns-monitors/:dnsMonitorPublicId` The response contains the DNS monitor itself and does not embed the full customer record. ## Example response ```json { "id": 1, "publicId": "3c741f27-7015-4202-93ea-0f97cc6bc769", "organizationId": 2, "customerId": 2, "customerName": "Zaskoku & Haupt GbR", "name": "haupt.design", "hostname": "haupt.design", "checkInterval": 30, "timeoutSeconds": 30, "dnsConfig": { "rrtypes": ["A"], "matchMode": "exact", "triggerOn": { "mismatch": true, "resolveError": true }, "expectedValues": { "A": ["76.76.21.21"] } }, "status": "active", "notificationPhoneNumber": null, "notificationEmail": null, "lastCheckedAt": "2026-04-03T14:55:00.005Z", "createdAt": "2026-02-23T20:24:54.731Z", "updatedAt": "2026-04-03T14:55:01.193Z" } ``` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET \ "$BASE_URL/api/dns-monitors/11111111-1111-4111-8111-111111111111" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Common errors - `400 DNS monitor public ID (UUID) required` - `401 Unauthorized` - `404 DNS monitor not found` when the monitor does not exist **or belongs to another customer or organization** (the two cases are indistinguishable on purpose)
### Get DNS Monitor Alert History
URL: https://docs.uptimeify.io/api/monitors/dns-monitors/get-dns-monitor-alert-history
Description: Returns notification/escalation attempts (alert history) for incidents of a DNS monitor.
Summary: `GET /api/dns-monitors/:dnsMonitorPublicId/alert-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `dnsMonitorPublicId` (Path, required): DNS monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). - `limit` (number, optional): Items per page (default: `25`; max `100`). Ignored in favor of export defaults when `format=csv` or `download=1` (default `10000`, max `50000`). - `status` (string, optional): `sent` or `failed`. - `from` / `to` (ISO date string, optional): Filter by `sentAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` to force an attachment download, `0` (default) for the page. - `envelope` (string, optional): `items` answers as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/dns-monitors/11111111-1111-4111-8111-111111111111/alert-history?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [ { "id": 987, "incidentId": 123, "type": "slack", "status": "sent", "channelName": "Ops Slack", "channelType": "slack", "channelConfig": null, "sentAt": "2026-02-26T12:11:00.000Z", "errorMessage": null } ], "total": 1, "page": 1, "perPage": 25 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }` (`perPage` is the `limit`). Without it the endpoint still answers the current form `{ data, total, page, pageCount }`, which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. Each entry is one delivery attempt to one notification channel. `status` is `sent` or `failed` (with `errorMessage` set on failure); `channelType` is the channel type (e.g. `email`, `slack`, `opsgenie`). `channelConfig` has secrets redacted. When `format=csv` (or `download=1`), the response is a `text/csv` (or `application/json` for `format=json&download=1`) attachment instead of the paginated JSON list above. ## Common Errors - `400 DNS monitor public ID (UUID) required` if `:dnsMonitorPublicId` is invalid - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the monitor
### Get DNS Monitor Check History
URL: https://docs.uptimeify.io/api/monitors/dns-monitors/get-dns-monitor-check-history
Description: Returns recent DNS check results for a monitor.
Summary: `GET /api/dns-monitors/:dnsMonitorPublicId/check-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `dnsMonitorPublicId` (Path, required): DNS monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). A page counts check cycles, not rows: one cycle has one row per location. - `limit` (number, optional): Cycles per page (default: `10`; max `100`). With `format=csv` or `download=1` the export defaults apply instead (default `10000`, max `50000` rows). - `status` (string, optional): `success` or `failure` (`failure` also matches `timeout`). On minute rows: no failed location, or at least one. - `minMs` / `maxMs` (number, optional): Filter by response time range (`timingTotal`; on minute rows the minute average). - `from` / `to` (ISO date string, optional): Filter by `checkedAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` forces an attachment download. ## cURL ```bash curl "https://YOUR_DOMAIN/api/dns-monitors/44444444-4444-4444-8444-444444444444/check-history?page=1&limit=10" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "data": [ { "id": "33c53ac4-a2bc-475c-a904-8d3d6aab2979", "status": "success", "success": true, "errorMessage": null, "checkedAt": "2026-10-01T05:40:55.690Z", "responseTimeMs": 29, "location": { "name": "Paris (FR)", "code": "par" }, "resolution": "raw" }, { "id": "1min-2026-09-30T15:55:00.000Z", "status": "success", "success": true, "errorMessage": null, "checkedAt": "2026-09-30T15:55:00.000Z", "responseTimeMs": 54, "location": null, "resolution": "1min", "totalLocations": 2, "failedLocations": 0 } ], "total": 864, "page": 17, "pageCount": 87, "resolution": "mixed", "rawWindowFrom": "2026-09-30T16:00:00.000Z" } ``` - `resolution` per row: `raw` is a single check with location and error message; `1min` is one minute across all locations, without location or error message, with `totalLocations` and `failedLocations`. - `resolution` of the page: `raw`, `1min` or `mixed` (the page spans the boundary). - `rawWindowFrom`: where individual checks begin; older rows are minute rows. With `format=csv` (or `download=1`) the response is a `text/csv` attachment (or `application/json` for `format=json&download=1`) instead of the paginated JSON above. CSV columns: `checkedAt,status,responseTimeMs,location,errorMessage,resolution`. The JSON export (`format=json&download=1`) additionally carries `diagnostics` (resolver answers) for each raw check. ## Data retention Individual checks, with location and error message, are kept for 24 hours. Older entries come from minute aggregates (30 days), one row per minute without location or error message. Daily figures (24 months) are available through the monitor details. ## Common errors - `400 DNS monitor public ID (UUID) required` - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status`, `minMs` or `maxMs` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` - `403 Forbidden`
### Get DNS Monitor Incident History
URL: https://docs.uptimeify.io/api/monitors/dns-monitors/get-dns-monitor-incident-history
Description: Returns incidents for a single DNS monitor (latest 100), including a computed duration.
Summary: `GET /api/dns-monitors/:dnsMonitorPublicId/incident-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `dnsMonitorPublicId` (Path, required): DNS monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). - `limit` (number, optional): Items per page (default: `25`; max `100`). Ignored in favor of export defaults when `format=csv` or `download=1` (default `10000`, max `50000`). - `status` (string, optional): `open`, `acknowledged`, or `resolved`. - `type` (string, optional): `downtime`, `http_status`, `ssl_expiry`, `ssl_critical`, `ssl_warning`, `response_time`, `dnsbl`, `domain_expiry_warning`, `critical`, or `inconclusive`. - `from` / `to` (ISO date string, optional): Filter by `startedAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` to force an attachment download, `0` (default) for the page. - `envelope` (string, optional): `items` answers as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/dns-monitors/11111111-1111-4111-8111-111111111111/incident-history?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [ { "id": 123, "publicId": "55555555-5555-4555-8555-555555555555", "type": "downtime", "status": "resolved", "startedAt": "2026-02-26T12:10:00.000Z", "endedAt": "2026-02-26T12:12:30.000Z", "durationMs": 150000, "statusCode": null, "errorMessage": "connect ETIMEDOUT", "details": "connect ETIMEDOUT", "isOngoing": false } ], "total": 1, "page": 1, "perPage": 25 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }` (`perPage` is the `limit`). Without it the endpoint still answers the current form `{ data, total, page, pageCount }`, which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. **Deprecated field:** `duration` (text, e.g. `2m 30s`) is still sent next to `durationMs` until it is removed on 2027-01-18. Read `durationMs`. `status` is `open`, `acknowledged`, or `resolved`. Ongoing incidents have a `null` `endedAt` and `isOngoing: true`. When `format=csv` (or `download=1`), the response is a `text/csv` (or `application/json` for `format=json&download=1`) attachment instead of the paginated JSON list above. ## Common Errors - `400 DNS monitor public ID (UUID) required` if `:dnsMonitorPublicId` is invalid - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status` or `type` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the monitor
### List DNS Monitors
URL: https://docs.uptimeify.io/api/monitors/dns-monitors/list-dns-monitors
Description: Lists DNS monitors for an organization (with pagination).
Summary: `GET /api/dns-monitors` Each item contains the DNS monitor itself and does not embed the full customer record. ## Query Parameters - `organizationId` (optional): defaults to your session organization - `customerId` (optional) - `search` (optional) - `page` (optional, default `1`) - `perPage` (optional, default `50`, max `200`) ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET \ "$BASE_URL/api/dns-monitors?organizationId=1&page=1&perPage=50" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [ { "id": 5, "publicId": "79fbe9b0-f9c6-4026-86de-1dbebc84d9bb", "organizationId": 2, "customerId": 2, "customerName": "Zaskoku & Haupt GbR", "name": "Primary DNS Monitor", "hostname": "claas.sh", "checkInterval": 30, "timeoutSeconds": 30, "dnsConfig": {}, "allowedCheckCountryCodes": null, "status": "active", "notificationPhoneNumber": null, "notificationEmail": null, "lastCheckedAt": "2026-04-03T14:54:56.561Z", "createdAt": "2026-04-03T14:54:56.383Z", "updatedAt": "2026-04-03T14:54:56.740Z", "uptimeDay": "100.00", "uptimeMonth": "99.87", "uptimeYear": "99.94", "avgResponseDay": 24, "avgResponseMonth": 27, "avgResponseYear": 26, "responseGraph": { "values": [24, 25, null], "avg": 24 }, "upSinceAt": "2026-04-01T08:12:03.000Z", "isDown": false, "tags": [] } ], "total": 0, "page": 1, "perPage": 50 } ``` ## Inline metrics Every item carries the same rolled-up metrics the other monitor list endpoints return. They are computed per monitor over the calendar day, month and year in UTC. | Field | Type | Meaning | |------|-----|---------| | `uptimeDay` / `uptimeMonth` / `uptimeYear` | string | Uptime percentage with two decimals, e.g. `"99.94"` | | `avgResponseDay` / `avgResponseMonth` / `avgResponseYear` | number \| null | Average response time in milliseconds; `null` when nothing was measured in that window | | `responseGraph` | object | `{ values, avg }` for the last 24 hours, one entry per hour; an hour with no successful check is `null` | | `upSinceAt` | string \| null | ISO timestamp the monitor has been up since, `null` while it is down | | `isDown` | boolean | Whether the monitor is currently in an unresolved incident | The day figures are read from the raw check data, the month and year from continuous aggregates, so a value may lag the newest check by a few minutes in the month and year windows. ## Common errors - `400 Bad Request` (`invalidRequestBody`) if `page` or `perPage` is not a positive integer, `sortOrder` is not `asc`/`desc`, or `tags` is not a comma-separated list of tag ids - `400 Invalid organizationId` when `organizationId` is invalid - `400 Invalid customerId` when `customerId` is invalid - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the organization
### Trigger DNS Check
URL: https://docs.uptimeify.io/api/monitors/dns-monitors/trigger-check-dns-monitor
Description: Triggers an immediate DNS check across eligible monitoring locations.
Summary: `POST /api/dns-monitors/:dnsMonitorPublicId/trigger-check` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST \ "$BASE_URL/api/dns-monitors/11111111-1111-4111-8111-111111111111/trigger-check" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "success": true, "message": "Checks triggered successfully", "dnsMonitorId": 123, "locationCodes": ["de-nbg"], "queueNames": ["dns-monitor-checks-de-nbg"] } ``` ## Common errors - `400 DNS monitor public ID (UUID) required` - `401 Unauthorized` - `403 Forbidden` (requires write access) - `429 Check recently triggered` (`data.retryAfterMs`) when the same monitor was triggered within the last 10 seconds - `503 No active monitoring locations available`
### Update DNS Monitor
URL: https://docs.uptimeify.io/api/monitors/dns-monitors/update-dns-monitor
Description: Updates a DNS monitor.
Summary: `PATCH /api/dns-monitors/:dnsMonitorPublicId` Notes: - Readonly users may only change `status`. - Global supporters cannot update DNS monitors. - If you send `customerId`, it accepts either the internal numeric ID or the customer `publicId` UUID. ## Request Body (example) ```json { "customerId": "6764e84f-f02a-43e6-a46d-cecaec556723", "status": "maintenance", "name": "Primary DNS Monitor", "hostname": "claas.sh", "checkInterval": 30, "timeoutSeconds": 30, "dnsConfig": { "rrtypes": ["A"], "matchMode": "exact", "expectedValues": { "A": ["76.76.21.21"] }, "triggerOn": { "resolveError": true, "mismatch": true } } } ``` If you send `dnsConfig`, it must include `rrtypes`, `matchMode`, and at least one `expectedValues` entry for every RR type listed. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PATCH \ "$BASE_URL/api/dns-monitors/11111111-1111-4111-8111-111111111111" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"customerId":"6764e84f-f02a-43e6-a46d-cecaec556723","status":"maintenance","name":"Primary DNS Monitor","hostname":"claas.sh","checkInterval":30,"timeoutSeconds":30,"dnsConfig":{"rrtypes":["A"],"matchMode":"exact","expectedValues":{"A":["76.76.21.21"]},"triggerOn":{"resolveError":true,"mismatch":true}}}' ``` ## Common errors - `400 Bad Request` (`invalidRequestBody`) if `name` is not a non-empty string of at most 255 characters, or `allowedCheckCountryCodes` is neither an array of country codes nor `null` - `400 Bad Request` (`invalidTimeoutSeconds`) if `timeoutSeconds` is not an integer between 1 and 60 - `400 Bad Request` (`invalidConfig`) if a config field (`config`, or the type-specific one) is not an object - `400 DNS monitor ID is required` - `400 Invalid status` - `400 Invalid Customer identifier` - `400 Expected values are required for RR type ` - `401 Unauthorized` - `403 Forbidden` - `404 Customer not found` ## Response Returns the updated DNS monitor object. See [Error Codes](/api/error-codes-and-known-pitfalls) for error responses.
### DNSBL Monitoring (Customer IPs)
URL: https://docs.uptimeify.io/api/monitors/dnsbl-monitoring
Description: DNSBL monitoring is configured via customer IPs. These IPs are periodically checked against DNS-based blacklists.
Summary: ## Endpoints - [List Customer IPs (Org)](/api/monitors/dnsbl-monitoring/list-customer-ips) - [Get Customer IP](/api/monitors/dnsbl-monitoring/get-customer-ip) - [Update Customer IP](/api/monitors/dnsbl-monitoring/update-customer-ip) - [Delete Customer IP](/api/monitors/dnsbl-monitoring/delete-customer-ip) - [List Customer IPs (Customer)](/api/monitors/dnsbl-monitoring/list-customer-ips-for-customer) - [Create Customer IP (Customer)](/api/monitors/dnsbl-monitoring/create-customer-ip-for-customer)
### Create Customer Ip For Customer
URL: https://docs.uptimeify.io/api/monitors/dnsbl-monitoring/create-customer-ip-for-customer
Summary: title: Create Customer IP (Customer) description: POST /api/customers/:customerPublicId/ips --- # Create Customer IP (Customer) `POST /api/customers/:customerPublicId/ips` Creates a new customer IP for DNSBL monitoring. ## Request Body ```json { "ipAddress": "203.0.113.10", "label": "Mail Server", "ipFamily": "v4", "status": "active" } ``` Notes: - `customerPublicId` should be the customer public UUID. Legacy numeric customer IDs remain supported for compatibility. - `ipFamily` is optional; if omitted, it is inferred from the IP address. - If `ipFamily` is provided, it must match the IP address version. - Creating an `active` IP may be blocked by quota limits. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/customers/6bfec6f6-245a-47ce-843b-157d97d56f88/ips" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"ipAddress":"203.0.113.10","label":"Mail Server","status":"active"}' ``` ## Response `200` with the customer IP record, and the record now carries a `deduplicated` flag. Repeating a request with exactly the same body does NOT create a second, separately billable monitor: the entry that already exists is returned again and the response carries `"deduplicated": true`, while a first creation carries `"deduplicated": false`. Both cases answer `200`. The comparison covers the whole request and not just `ipAddress`, so the same address sent again with a different `label` or `status` is a different request and does create a second entry -- there is no uniqueness check on the address itself. A recognised repeat is not counted against the active-IP limit. ## Common errors - `400 Invalid Customer identifier` when `:customerPublicId` is missing/invalid - `400 Invalid IP address` when `ipAddress` is invalid - `400 IP family mismatch...` when `ipFamily` does not match the IP - `401 Unauthorized` when you are not logged in - `403 Forbidden` for readonly/global supporter users, or when you cannot access the customer - `403 Active IP limit reached...` when creating/activating would exceed your quota - `404 Customer not found` when the customer does not exist - there is no `409` on this route: an address that is already present under this customer with exactly the same body comes back as a recognised repeat (see Response), and with a different body it becomes a second entry
### Delete Customer IP
URL: https://docs.uptimeify.io/api/monitors/dnsbl-monitoring/delete-customer-ip
Description: Deletes a customer IP.
Summary: `DELETE /api/customer-ips/:customerIpPublicId` Notes: - Readonly users and global supporters cannot delete customer IPs. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X DELETE "$BASE_URL/api/customer-ips/11111111-1111-4111-8111-111111111111" \ -H "Authorization: Bearer $TOKEN" ``` ## Example Response ```json { "success": true } ``` ## Common errors - `400 Invalid IP identifier` when `:customerIpPublicId` is neither a valid UUID nor a legacy numeric ID - `401 Unauthorized` when you are not logged in - `403 Forbidden` for readonly/global supporter users, or when you cannot access the customer - `404 IP not found` when the IP does not exist ## Permissions Closed to the `readonly` role. A read-only login deletes no IP, whatever its ownership class, and neither does an API token it issued: a token inherits the role of the user who created it. Editing a `self_service` IP stays open to that role. A customer-scoped caller is bound by ownership class on top of that: a `managed` IP is refused with `managed_by_organization` unless its customer carries `canEditManaged`.
### Get Customer IP
URL: https://docs.uptimeify.io/api/monitors/dnsbl-monitoring/get-customer-ip
Description: Returns a customer IP including DNSBL status (if available).
Summary: `GET /api/customer-ips/:customerIpPublicId` The response contains the customer IP itself and, if available, a `dnsbl` object. It does not embed the full customer record. ## Path Parameters - `customerIpPublicId` (recommended): customer IP public UUID - Backward compatibility: legacy numeric IDs are still accepted ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/customer-ips/11111111-1111-4111-8111-111111111111" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example response ```json { "id": 1, "publicId": "a19effb9-eb5f-459b-b5d6-2f615b574651", "customerId": 2, "customerName": "Zaskoku & Haupt GbR", "label": "Kurbelix Adminserver", "ipAddress": "77.75.254.185", "ipFamily": "v4", "status": "active", "createdAt": "2026-02-03T15:06:46.469Z", "updatedAt": "2026-02-03T15:06:46.469Z", "dnsbl": { "isListed": true, "listedCount": 1, "listings": [ { "name": "all.s5h.net", "reason": "Listed in all.s5h.net", "listKey": "all.s5h.net", "delistUrl": "http://s5h.net", "resultCode": "127.0.0.2" } ], "lastError": null, "lastCheckedAt": "2026-04-03T15:13:00.083Z", "lastChangedAt": "2026-02-04T10:00:00.121Z", "lastListedAt": "2026-04-03T15:13:00.083Z", "lastCleanAt": null, "lastNotifiedListedAt": "2026-04-02T20:55:04.969Z", "lastNotifiedCleanAt": null } } ``` ## Common errors - `400 Invalid IP identifier` when `:customerIpPublicId` is neither a valid UUID nor a legacy numeric ID - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the customer - `404 IP not found` when the IP does not exist
### List Customer IPs (Org)
URL: https://docs.uptimeify.io/api/monitors/dnsbl-monitoring/list-customer-ips
Description: Lists customer IPs within an organization (pagination + search). This is the primary API for DNSBL monitoring configuration.
Summary: `GET /api/customer-ips` ## Query Parameters - `organizationId` (optional): defaults to your session organization - `customerId` (optional): accepts the customer public UUID (recommended) or a legacy numeric customer ID - `search` (optional) - `page` (optional, default `1`) - `perPage` (optional, default `50`, max `200`) ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/customer-ips?organizationId=1&page=1&perPage=50" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [], "total": 0, "page": 1, "perPage": 50 } ``` ## Common errors - `400 Organization ID required` when the organization cannot be derived - `400` query validation errors (e.g. invalid `organizationId`, `customerId`, `page`, `perPage`) - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the organization
### List Customer Ips For Customer
URL: https://docs.uptimeify.io/api/monitors/dnsbl-monitoring/list-customer-ips-for-customer
Summary: title: List Customer IPs (Customer) description: GET /api/customers/:customerPublicId/ips --- # List Customer IPs (Customer) `GET /api/customers/:customerPublicId/ips` Lists IPs for a single customer, including DNSBL status. ## Path Parameters - `customerPublicId` (recommended): Customer public UUID - Legacy compatibility: numeric customer IDs are still accepted ## Query Parameters | Parameter | Type | Default | Description | |---|---|---|---| | `envelope` | string | none | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/customers/6bfec6f6-245a-47ce-843b-157d97d56f88/ips?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response Returns the customer's IP objects; each item may include a `dnsbl` object. **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form (a bare array of the same items), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. ## Common errors - `400 Invalid Customer identifier` when `:customerPublicId` is missing/invalid - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the customer - `404 Customer not found` when the customer does not exist
### Update Customer IP
URL: https://docs.uptimeify.io/api/monitors/dnsbl-monitoring/update-customer-ip
Description: Updates a customer IP (e.g. label or status).
Summary: `PATCH /api/customer-ips/:customerIpPublicId` Notes: - Readonly users and global supporters cannot update customer IPs. - Activating an IP can be denied when quota limits are reached. ## Request Body ```json { "label": "Mail Server", "status": "active" } ``` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PATCH "$BASE_URL/api/customer-ips/11111111-1111-4111-8111-111111111111" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"label":"Mail Server","status":"active"}' ``` ## Response Returns the updated customer IP record. ## Common errors - `400 Invalid IP identifier` when `:customerIpPublicId` is neither a valid UUID nor a legacy numeric ID - `400` body validation errors (e.g. invalid `status`) - `401 Unauthorized` when you are not logged in - `403 Forbidden` for readonly/global supporter users, or when you cannot access the customer - `403 Active IP limit reached...` when activating would exceed your quota - `404 IP not found` when the IP does not exist
### Domain Expiry Monitoring (Customer Domains)
URL: https://docs.uptimeify.io/api/monitors/domain-expiry-monitoring
Description: Domain expiry monitoring is configured via customer domains.
Summary: ## Endpoints - [Create Customer Domain (Customer)](/api/monitors/domain-expiry-monitoring/create-customer-domain) - [List Customer Domains (Org)](/api/monitors/domain-expiry-monitoring/list-customer-domains) - [Get Customer Domain](/api/monitors/domain-expiry-monitoring/get-customer-domain) - [Update Customer Domain](/api/monitors/domain-expiry-monitoring/update-customer-domain) - [Delete Customer Domain](/api/monitors/domain-expiry-monitoring/delete-customer-domain) - [List Domain Expiry (Websites)](/api/monitors/domain-expiry-monitoring/list-domain-expiry-websites)
### Create Customer Domain
URL: https://docs.uptimeify.io/api/monitors/domain-expiry-monitoring/create-customer-domain
Summary: title: Create Customer Domain (Customer) description: POST /api/customers/:customerPublicId/domains --- # Create Customer Domain (Customer) `POST /api/customers/:customerPublicId/domains` Creates a customer domain for expiry monitoring. ## Request Body ```json { "domainName": "deinkunde.com", "label": "Main Domain", "status": "active", "expiryWarningDays": 30, "expiryErrorDays": 7 } ``` Notes: - `customerPublicId` should be the customer public UUID. Legacy numeric customer IDs remain supported for compatibility. - `domainName` must be a valid domain like `deinkunde.com` (no protocol, no path). - Creating an `active` domain may be blocked by quota limits. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/customers/6bfec6f6-245a-47ce-843b-157d97d56f88/domains" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"domainName":"deinkunde.com","label":"Main Domain","status":"active","expiryWarningDays":30,"expiryErrorDays":7}' ``` ## Response `200` with the customer domain record, and the record now carries a `deduplicated` flag. Repeating a request with exactly the same body does NOT create a second, separately billable monitor: the entry that already exists is returned again and the response carries `"deduplicated": true`, while a first creation carries `"deduplicated": false`. Both cases answer `200`. The comparison covers the whole request and not just `domainName`, so the same domain sent again with a different `label`, `status`, `expiryWarningDays` or `expiryErrorDays` is a different request and does create a second entry -- there is no uniqueness check on the domain name itself. A recognised repeat consumes no quota and never moves the organization up a quota tier. ## Common errors - `400 Invalid Customer identifier` when `:customerPublicId` is missing/invalid - `400 Invalid domain name...` when `domainName` is invalid - `401 Unauthorized` when you are not logged in - `403 Forbidden` for readonly/global supporter users, or when you cannot access the customer - `403 Active domain limit reached...` when creating/activating would exceed your quota - `404 Customer not found` when the customer does not exist
### Delete Customer Domain
URL: https://docs.uptimeify.io/api/monitors/domain-expiry-monitoring/delete-customer-domain
Description: Deletes a customer domain.
Summary: `DELETE /api/customer-domains/:customerDomainPublicId` Notes: - Readonly users and global supporters cannot delete customer domains. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X DELETE "$BASE_URL/api/customer-domains/22222222-2222-4222-8222-222222222222" \ -H "Authorization: Bearer $TOKEN" ``` ## Example Response ```json { "success": true } ``` ## Common errors - `400 Invalid Domain identifier` when `:customerDomainPublicId` is neither a valid UUID nor a legacy numeric ID - `401 Unauthorized` when you are not logged in - `403 Forbidden` for readonly/global supporter users, or when you cannot access the domain/customer - `404 Domain not found` when the domain does not exist ## Permissions Closed to the `readonly` role. A read-only login deletes no domain, whatever its ownership class, and neither does an API token it issued: a token inherits the role of the user who created it. Editing a `self_service` domain stays open to that role. A customer-scoped caller is bound by ownership class on top of that: a `managed` domain is refused with `managed_by_organization` unless its customer carries `canEditManaged`.
### Get Customer Domain
URL: https://docs.uptimeify.io/api/monitors/domain-expiry-monitoring/get-customer-domain
Description: Returns a single customer domain.
Summary: `GET /api/customer-domains/:customerDomainPublicId` The response contains the customer domain itself and does not embed the full customer record. ## Path Parameters - `customerDomainPublicId` (recommended): customer domain public UUID - Backward compatibility: legacy numeric IDs are still accepted Notes: - Some registries/TLDs (e.g. `.de`) may not publish an expiration date via RDAP. In that case, `expiry.domainExpiresAt` can be `null` and `expiry.lastError` may contain an explanatory message. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/customer-domains/22222222-2222-4222-8222-222222222222" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example response ```json { "id": 20, "publicId": "d70884d9-4cef-4fe5-9b15-341b7dd9e196", "customerId": 2, "customerName": "Zaskoku & Haupt GbR", "label": "Primary Domain", "domainName": "cacheassist.io", "status": "active", "expiryWarningDays": 30, "expiryErrorDays": 7, "createdAt": "2026-04-03T15:28:40.602Z", "updatedAt": "2026-04-03T15:28:40.602Z", "expiry": { "domainExpiresAt": null, "domainRegistrar": null, "isExpired": false, "lastError": "RDAP query error for cacheassist.io: fetch failed", "lastCheckedAt": "2026-04-03T15:29:00.200Z", "lastChangedAt": null, "lastNotifiedWarningAt": null, "lastNotifiedErrorAt": null, "lastNotifiedExpiredAt": null } } ``` ## Common errors - `400 Invalid Domain identifier` when `:customerDomainPublicId` is neither a valid UUID nor a legacy numeric ID - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the domain/customer - `404 Domain not found` when the domain does not exist
### List Customer Domains (Org)
URL: https://docs.uptimeify.io/api/monitors/domain-expiry-monitoring/list-customer-domains
Description: Lists customer domains within an organization (pagination + search).
Summary: `GET /api/customer-domains` ## Query Parameters - `organizationId` (optional): defaults to your session organization - `customerId` (optional): accepts the customer public UUID (recommended) or a legacy numeric customer ID - `search` (optional) - `page` (optional, default `1`) - `perPage` (optional, default `50`, max `200`) ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/customer-domains?organizationId=1&page=1&perPage=50" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response Returns a paginated response: ```json { "items": [ { "id": 1, "publicId": "34eb0ec1-315d-45c4-aefe-0e5d12b11183", "customerId": 2, "customerName": "Zaskoku & Haupt GbR", "customerPublicId": "6764e84f-f02a-43e6-a46d-cecaec556723", "label": null, "domainName": "digitalduett.com", "status": "active", "expiryWarningDays": 30, "expiryErrorDays": 7, "createdAt": "2026-02-13T21:21:03.001Z", "updatedAt": "2026-02-13T21:21:03.001Z", "expiry": { "domainExpiresAt": "2026-12-20T20:44:45.000Z", "domainRegistrar": "NameCheap, Inc.", "isExpired": false, "lastError": null, "lastCheckedAt": "2026-04-03T10:59:00.321Z", "lastChangedAt": "2026-04-03T10:59:00.321Z", "lastNotifiedWarningAt": null, "lastNotifiedErrorAt": null, "lastNotifiedExpiredAt": null } } ], "total": 0, "page": 1, "perPage": 50 } ``` Each item includes flat customer fields plus an `expiry` object (or `null`). ## Common errors - `400 Organization ID required` when the organization cannot be derived - `400` query validation errors (e.g. invalid `organizationId`, `customerId`, `page`, `perPage`) - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the organization
### List Domain Expiry (Websites)
URL: https://docs.uptimeify.io/api/monitors/domain-expiry-monitoring/list-domain-expiry-websites
Description: Lists websites with latest known domain expiry information.
Summary: `GET /api/domains` ## Query Parameters - `organizationId` (optional): defaults to your session organization - `customerId` (optional) - `search` (optional) - `page` (optional, default `1`) - `perPage` (optional, default `50`, max `200`) ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/domains?organizationId=1&page=1&perPage=50" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "items": [ { "id": 101, "name": "Example Website", "url": "https://deinkunde.com", "status": "active", "customerId": 10, "customerName": "Example Customer", "checkDomainExpiryEnabled": true, "domainExpiryNoticeDays": 30, "domainExpiryErrorDays": 7, "domainExpiresAt": "2026-12-31T00:00:00.000Z", "domainRegistrar": "Example Registrar", "lastDomainCheckAt": "2026-03-03T10:00:00.000Z", "daysUntilExpiry": 303, "expiryStatus": "ok" } ], "total": 1, "page": 1, "perPage": 50 } ``` ## Field notes - `expiryStatus` can be: `ok`, `warning`, `critical`, `expired`, `unknown`, `disabled`. - `daysUntilExpiry` is `null` when no expiration date is available. ## Common errors - `400 Organization ID required` when the organization cannot be derived - `400 Invalid customerId` when `customerId` is invalid - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the organization
### Update Customer Domain
URL: https://docs.uptimeify.io/api/monitors/domain-expiry-monitoring/update-customer-domain
Description: Updates a customer domain (e.g. label, status, expiry thresholds).
Summary: `PATCH /api/customer-domains/:customerDomainPublicId` Notes: - Global supporters cannot update customer domains. A readonly or customer-scoped login may update its own `self_service` domains; a `managed` domain stays locked unless the organization granted `canEditManaged`. - The domain name is fixed at creation and cannot be changed here. The endpoint therefore does not re-check whether the TLD supports RDAP expiry lookups (it did until 06.09.2026): a stored domain on a TLD without RDAP can still be relabelled, given other thresholds and, above all, disabled. - Activating a disabled domain can be denied when quota limits are reached. ## Request Body ```json { "label": "Main Domain", "status": "active", "expiryWarningDays": 30, "expiryErrorDays": 7 } ``` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PATCH "$BASE_URL/api/customer-domains/22222222-2222-4222-8222-222222222222" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"status":"active"}' ``` ## Response Returns the updated customer domain record. ## Common errors - `400` body validation errors (e.g. invalid thresholds) - `400 Invalid Domain identifier` when `:customerDomainPublicId` is neither a valid UUID nor a legacy numeric ID - `401 Unauthorized` when you are not logged in - `403 Forbidden` for global supporters, for a `managed` domain without `canEditManaged`, or when you cannot access the domain/customer - `403 Active domain limit reached...` when activating would exceed your quota - `404 Domain not found` when the domain does not exist
### FTP Monitors
URL: https://docs.uptimeify.io/api/monitors/ftp-monitors
Description: Manage FTP monitors.
Summary: Path-based FTP monitor endpoints use `ftpMonitorPublicId` UUIDs. ## Endpoints - [List FTP Monitors](/api/monitors/ftp-monitors/list-ftp-monitors) - [Create FTP Monitor](/api/monitors/ftp-monitors/create-ftp-monitor) - [Get FTP Monitor](/api/monitors/ftp-monitors/get-ftp-monitor) - [Get FTP Monitor Details](/api/monitors/ftp-monitors/get-ftp-monitor-details) - [Get FTP Monitor Check History](/api/monitors/ftp-monitors/get-ftp-monitor-check-history) - [Update FTP Monitor (Change Status)](/api/monitors/ftp-monitors/update-ftp-monitor) - [Delete FTP Monitor](/api/monitors/ftp-monitors/delete-ftp-monitor) - [Trigger FTP Check](/api/monitors/ftp-monitors/trigger-check-ftp-monitor)
### Create FTP Monitor
URL: https://docs.uptimeify.io/api/monitors/ftp-monitors/create-ftp-monitor
Description: Creates a new FTP monitor.
Summary: `POST /api/ftp-monitors` ## Authentication This endpoint requires an API token: `Authorization: Bearer ` ## Request Body - `customerId` (required, number | string): internal numeric customer ID or customer `publicId` UUID - `name` (required, string) - `hostname` (required, string): Must be a hostname (no protocol, no path). - `port` (optional, number | null): If omitted/null, the worker uses a default port. - `status` (optional): `active`, `maintenance`, `disabled` (also accepts `inactive` and normalizes it to `disabled`) - `checkInterval` (optional, number): Minutes (min: 1, max: 60) - `timeoutSeconds` (optional, number): Seconds (min: 1, max: 60) - `checkMode` (optional, string): `protocol` | `tcp`. Defaults to `protocol`. - In `tcp` mode the monitor performs a bare TCP port-reachability check: `ftpConfig` is not required and is not stored. In `protocol` mode the full FTP login check runs (existing behavior). - `ftpConfig` (optional, object): FTP connection options (stored as JSON) - Required (`user` + `password`) unless `checkMode` is `tcp`. ### `ftpConfig` The monitoring worker reads these keys: - `user` (optional, string): Defaults to `anonymous` - `password` (optional, string): Defaults to `anonymous@` - `secure` (optional, boolean | `"implicit"`): - `false` (default): plain FTP - `true`: explicit TLS - `"implicit"`: implicit TLS (worker defaults port to `990` when `port` is not provided) ```json { "customerId": "6764e84f-f02a-43e6-a46d-cecaec556723", "name": "FTP Availability", "hostname": "claas.sh", "port": 21, "status": "active", "checkInterval": 5, "timeoutSeconds": 30, "ftpConfig": { "user": "root", "password": "exampleRoot", "secure": "explicit" } } ``` ### Duplicates If this customer already has a monitor with the same `hostname` (case and a trailing dot do not count), `port` and `checkMode`, the request is refused with `409` and `data.code` `monitorAlreadyExists`. `data.existingId` and `data.existingPublicId` name the existing monitor. Send `"allowDuplicate": true` to create the second monitor anyway (for example with a different interval or other alert channels). - `allowDuplicate` (boolean, optional, default `false`): create the monitor even if it is a duplicate. Not stored. ```json { "statusCode": 409, "statusMessage": "A monitor for this target already exists for this customer. Send allowDuplicate: true to create it anyway.", "data": { "code": "monitorAlreadyExists", "existingId": 300, "existingPublicId": "44444444-4444-4444-8444-444444444444" } } ``` ### Limit per target host An organization can have at most 100 monitors for the same target host, counted across all monitor types together (websites with HTTP, keyword, DNS website and Playwright with a real URL, plus TCP, ICMP, DNS, SSH, SMTP, FTP and IMAP/POP). The limit protects against the check fleet being misused as a load generator against third-party hosts. The exact hostname is compared: case, port, path and a trailing dot do not count, but `www.example.com` and `example.com` are different hosts. Once the limit is reached, the request is refused with `403` and `data.code` `targetHostMonitorLimitReached`. `data.host` names the normalized host, `data.limit` the limit. `"allowDuplicate": true` does not lift the limit. The same check runs when a PATCH changes the `hostname`. A PATCH that keeps the host always succeeds, and existing monitors above the limit stay in place. If you need a higher limit, contact support. Independently of your organization, at most 300 monitors across all Uptimeify customers may target the same host. Beyond that, the request is refused with `403` and `data.code` `targetHostPlatformLimitReached`; `data.host` and `data.limit` are set as above, and the message does not reveal how many monitors other organizations have. ```json { "statusCode": 403, "statusMessage": "Target host monitor limit reached: your organization already has 100 monitors for example.com (maximum 100 per host). Remove monitors for this host or contact sup…
### Delete FTP Monitor
URL: https://docs.uptimeify.io/api/monitors/ftp-monitors/delete-ftp-monitor
Description: Deletes an FTP monitor.
Summary: `DELETE /api/ftp-monitors/:ftpMonitorPublicId` ## Authentication `Authorization: Bearer ` ## Parameters - `ftpMonitorPublicId` (Path, required): FTP monitor public UUID. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X DELETE \ "$BASE_URL/api/ftp-monitors/55555555-5555-4555-8555-555555555555" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "success": true } ``` ## Common Errors - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have write access (e.g. global supporter or read-only) - `404 FTP monitor not found` if the monitor does not exist ## Permissions Closed to the `readonly` role. A read-only login deletes no monitor, whatever its ownership class, and neither does an API token it issued: a token inherits the role of the user who created it. Editing a `self_service` monitor stays open to that role. A customer-scoped caller is bound by ownership class on top of that: a `managed` monitor is refused with `managed_by_organization` unless its customer carries `canEditManaged`.
### Get FTP Monitor
URL: https://docs.uptimeify.io/api/monitors/ftp-monitors/get-ftp-monitor
Description: Returns details of a specific FTP monitor.
Summary: `GET /api/ftp-monitors/:ftpMonitorPublicId` The response contains the FTP monitor itself and does not embed the full customer record. ## Authentication `Authorization: Bearer ` ## Parameters - `ftpMonitorPublicId` (Path, required): FTP monitor public UUID. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET \ "$BASE_URL/api/ftp-monitors/55555555-5555-4555-8555-555555555555" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "id": 400, "organizationId": 1, "customerId": 10, "name": "Partner FTP", "hostname": "ftp.deinkunde.com", "port": 21, "status": "active", "checkInterval": 30, "timeoutSeconds": 30, "allowedCheckCountryCodes": null, "notificationPhoneNumber": null, "notificationEmail": null, "lastCheckedAt": null, "createdAt": "2026-02-25T10:00:00.000Z", "updatedAt": "2026-02-25T10:00:00.000Z", "config": { "user": "monitor", "password": "", "secure": false }, "ftpConfig": { "user": "monitor", "password": "", "secure": false } } ``` ## Common Errors - `400 FTP monitor public ID (UUID) required` if `ftpMonitorPublicId` is missing or invalid - `401 Unauthorized` if you are not authenticated - `404 FTP monitor not found` when the monitor does not exist **or belongs to another customer or organization** (the two cases are indistinguishable on purpose)
### Get FTP Monitor Alert History
URL: https://docs.uptimeify.io/api/monitors/ftp-monitors/get-ftp-monitor-alert-history
Description: Returns notification/escalation attempts (alert history) for incidents of a FTP monitor.
Summary: `GET /api/ftp-monitors/:ftpMonitorPublicId/alert-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `ftpMonitorPublicId` (Path, required): FTP monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). - `limit` (number, optional): Items per page (default: `25`; max `100`). Ignored in favor of export defaults when `format=csv` or `download=1` (default `10000`, max `50000`). - `status` (string, optional): `sent` or `failed`. - `from` / `to` (ISO date string, optional): Filter by `sentAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` to force an attachment download, `0` (default) for the page. - `envelope` (string, optional): `items` answers as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/ftp-monitors/11111111-1111-4111-8111-111111111111/alert-history?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [ { "id": 987, "incidentId": 123, "type": "slack", "status": "sent", "channelName": "Ops Slack", "channelType": "slack", "channelConfig": null, "sentAt": "2026-02-26T12:11:00.000Z", "errorMessage": null } ], "total": 1, "page": 1, "perPage": 25 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }` (`perPage` is the `limit`). Without it the endpoint still answers the current form `{ data, total, page, pageCount }`, which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. Each entry is one delivery attempt to one notification channel. `status` is `sent` or `failed` (with `errorMessage` set on failure); `channelType` is the channel type (e.g. `email`, `slack`, `opsgenie`). `channelConfig` has secrets redacted. When `format=csv` (or `download=1`), the response is a `text/csv` (or `application/json` for `format=json&download=1`) attachment instead of the paginated JSON list above. ## Common Errors - `400 FTP monitor public ID (UUID) required` if `:ftpMonitorPublicId` is invalid - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the monitor
### Get FTP Monitor Check History
URL: https://docs.uptimeify.io/api/monitors/ftp-monitors/get-ftp-monitor-check-history
Description: Returns recent FTP check results for a monitor.
Summary: `GET /api/ftp-monitors/:ftpMonitorPublicId/check-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `ftpMonitorPublicId` (Path, required): FTP monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). A page counts check cycles, not rows: one cycle has one row per location. - `limit` (number, optional): Cycles per page (default: `10`; max `100`). With `format=csv` or `download=1` the export defaults apply instead (default `10000`, max `50000` rows). - `status` (string, optional): `success` or `failure` (`failure` also matches `timeout`). On minute rows: no failed location, or at least one. - `minMs` / `maxMs` (number, optional): Filter by response time range (`timingTotal`; on minute rows the minute average). - `from` / `to` (ISO date string, optional): Filter by `checkedAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` forces an attachment download. ## cURL ```bash curl "https://YOUR_DOMAIN/api/ftp-monitors/44444444-4444-4444-8444-444444444444/check-history?page=1&limit=10" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "data": [ { "id": "33c53ac4-a2bc-475c-a904-8d3d6aab2979", "status": "success", "success": true, "errorMessage": null, "checkedAt": "2026-10-01T05:40:55.690Z", "responseTimeMs": 29, "location": { "name": "Paris (FR)", "code": "par" }, "resolution": "raw" }, { "id": "1min-2026-09-30T15:55:00.000Z", "status": "success", "success": true, "errorMessage": null, "checkedAt": "2026-09-30T15:55:00.000Z", "responseTimeMs": 54, "location": null, "resolution": "1min", "totalLocations": 2, "failedLocations": 0 } ], "total": 864, "page": 17, "pageCount": 87, "resolution": "mixed", "rawWindowFrom": "2026-09-30T16:00:00.000Z" } ``` - `resolution` per row: `raw` is a single check with location and error message; `1min` is one minute across all locations, without location or error message, with `totalLocations` and `failedLocations`. - `resolution` of the page: `raw`, `1min` or `mixed` (the page spans the boundary). - `rawWindowFrom`: where individual checks begin; older rows are minute rows. With `format=csv` (or `download=1`) the response is a `text/csv` attachment (or `application/json` for `format=json&download=1`) instead of the paginated JSON above. CSV columns: `checkedAt,status,responseTimeMs,location,errorMessage,resolution`. ## Data retention Individual checks, with location and error message, are kept for 24 hours. Older entries come from minute aggregates (30 days), one row per minute without location or error message. Daily figures (24 months) are available through the monitor details. ## Common Errors - `400 FTP monitor public ID (UUID) required` if `ftpMonitorPublicId` is missing or invalid - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status`, `minMs` or `maxMs` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access - `404 FTP monitor not found` if the monitor does not exist
### Get FTP Monitor Details
URL: https://docs.uptimeify.io/api/monitors/ftp-monitors/get-ftp-monitor-details
Description: Returns the FTP monitor detail page data in one call (mega endpoint).
Summary: `GET /api/ftp-monitors/:ftpMonitorPublicId/details` ## Authentication `Authorization: Bearer ` ## Parameters - `ftpMonitorPublicId` (Path, required): FTP monitor public UUID. ## Query Parameters - `range` (optional): `day` (default), `week`, `month`, `year` - `date` (optional): Reference date (ISO string) - `startDate` / `endDate` (optional): Override the time window (ISO strings) - `granularity` (optional): When omitted the server may aggregate automatically for large time ranges. Use `granularity=raw` to force raw data. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET \ "$BASE_URL/api/ftp-monitors/55555555-5555-4555-8555-555555555555/details?range=day" \ -H "Authorization: Bearer $TOKEN" ``` ## Example Response (shape) The response is a single object with these top-level keys: ```json { "ftpMonitorId": 400, "monitor": {}, "latestCheck": {}, "uptimeStats": { "day": "100.00", "month": "100.00", "year": "100.00", "dayAvgResponse": 120, "monthAvgResponse": 130, "yearAvgResponse": 140 }, "uptimeStatsMeta": {}, "monitoringData": { "responseTimeData": [], "statusData": [], "uptimePercentage": "100.00", "checkSuccessRatePercentage": "100.00", "totalChecks": 10, "successfulChecks": 10 }, "incidents": { "history": [], "total": 0, "ongoing": 0, "totalDowntime": "0s" }, "alerts": { "history": [], "total": 0, "notificationContext": {} }, "testResultLog": null, "maintenance": { "inMaintenance": false, "activeWindows": [], "allWindows": [] } } ``` ## Data retention Single checks are kept for 24 hours, minute aggregates for 30 days and daily aggregates for 24 months; a range older than 30 days returns one point per day. If the monitor has no check within the last 24 hours, `latestCheck` describes its last minute from the aggregate: `id` starts with `1min-`, `resolution` is `1min`, and `locationId` and `errorMessage` are `null`. ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `range` is not `day`/`week`/`month`/`year`, `date`/`startDate`/`endDate` is not a date, only one of `startDate`/`endDate` is given, `tz` is not an integer, or `granularity` is not `raw`/`aggregated` - `400 Invalid FTP monitor public ID (UUID)` if `ftpMonitorPublicId` is invalid - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access - `500 Failed to fetch FTP monitor details` on server errors
### Get FTP Monitor Incident History
URL: https://docs.uptimeify.io/api/monitors/ftp-monitors/get-ftp-monitor-incident-history
Description: Returns incidents for a single FTP monitor (latest 100), including a computed duration.
Summary: `GET /api/ftp-monitors/:ftpMonitorPublicId/incident-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `ftpMonitorPublicId` (Path, required): FTP monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). - `limit` (number, optional): Items per page (default: `25`; max `100`). Ignored in favor of export defaults when `format=csv` or `download=1` (default `10000`, max `50000`). - `status` (string, optional): `open`, `acknowledged`, or `resolved`. - `type` (string, optional): `downtime`, `http_status`, `ssl_expiry`, `ssl_critical`, `ssl_warning`, `response_time`, `dnsbl`, `domain_expiry_warning`, `critical`, or `inconclusive`. - `from` / `to` (ISO date string, optional): Filter by `startedAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` to force an attachment download, `0` (default) for the page. - `envelope` (string, optional): `items` answers as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/ftp-monitors/11111111-1111-4111-8111-111111111111/incident-history?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [ { "id": 123, "publicId": "55555555-5555-4555-8555-555555555555", "type": "downtime", "status": "resolved", "startedAt": "2026-02-26T12:10:00.000Z", "endedAt": "2026-02-26T12:12:30.000Z", "durationMs": 150000, "statusCode": null, "errorMessage": "connect ETIMEDOUT", "details": "connect ETIMEDOUT", "isOngoing": false } ], "total": 1, "page": 1, "perPage": 25 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }` (`perPage` is the `limit`). Without it the endpoint still answers the current form `{ data, total, page, pageCount }`, which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. **Deprecated field:** `duration` (text, e.g. `2m 30s`) is still sent next to `durationMs` until it is removed on 2027-01-18. Read `durationMs`. `status` is `open`, `acknowledged`, or `resolved`. Ongoing incidents have a `null` `endedAt` and `isOngoing: true`. When `format=csv` (or `download=1`), the response is a `text/csv` (or `application/json` for `format=json&download=1`) attachment instead of the paginated JSON list above. ## Common Errors - `400 FTP monitor public ID (UUID) required` if `:ftpMonitorPublicId` is invalid - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status` or `type` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the monitor
### List FTP Monitors
URL: https://docs.uptimeify.io/api/monitors/ftp-monitors/list-ftp-monitors
Description: Lists FTP monitors in an organization.
Summary: `GET /api/ftp-monitors` ## Authentication `Authorization: Bearer ` ## Parameters - `organizationId` (Query, optional): Organization ID. Defaults to the current user's organization. - `customerId` (Query, optional): Filter by customer ID. - `search` (Query, optional): Search by monitor name, hostname, or customer. - `page` (Query, optional): Page number (default: 1). - `perPage` (Query, optional): Items per page (default: 50, max: 200). Note: The results are also limited by your customer scope (if your account is restricted to a subset of customers). ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET \ "$BASE_URL/api/ftp-monitors?page=1&perPage=50&search=ftp" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "items": [ { "id": 400, "organizationId": 1, "customerId": 10, "customerName": "Example Customer", "name": "Partner FTP", "hostname": "ftp.deinkunde.com", "port": 21, "status": "active", "checkInterval": 30, "timeoutSeconds": 30, "allowedCheckCountryCodes": null, "config": { "user": "monitor", "password": "", "secure": false }, "notificationPhoneNumber": null, "notificationEmail": null, "lastCheckedAt": null, "createdAt": "2026-02-25T10:00:00.000Z", "updatedAt": "2026-02-25T10:00:00.000Z" } ], "total": 1, "page": 1, "perPage": 50 } ``` Each item contains the FTP monitor itself and a flat `customerName`, not a full embedded customer record. ## Inline metrics Every item carries the same rolled-up metrics the other monitor list endpoints return. They are computed per monitor over the calendar day, month and year in UTC. | Field | Type | Meaning | |------|-----|---------| | `uptimeDay` / `uptimeMonth` / `uptimeYear` | string | Uptime percentage with two decimals, e.g. `"99.94"` | | `avgResponseDay` / `avgResponseMonth` / `avgResponseYear` | number \| null | Average response time in milliseconds; `null` when nothing was measured in that window | | `responseGraph` | object | `{ values, avg }` for the last 24 hours, one entry per hour; an hour with no successful check is `null` | | `upSinceAt` | string \| null | ISO timestamp the monitor has been up since, `null` while it is down | | `isDown` | boolean | Whether the monitor is currently in an unresolved incident | The day figures are read from the raw check data, the month and year from continuous aggregates, so a value may lag the newest check by a few minutes in the month and year windows. ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `page` or `perPage` is not a positive integer, `sortOrder` is not `asc`/`desc`, or `tags` is not a comma-separated list of tag ids - `400 Invalid organizationId` if `organizationId` is not a valid number - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the organization
### Trigger FTP Check
URL: https://docs.uptimeify.io/api/monitors/ftp-monitors/trigger-check-ftp-monitor
Description: Triggers an immediate check from all eligible monitoring locations.
Summary: `POST /api/ftp-monitors/:ftpMonitorPublicId/trigger-check` ## Authentication `Authorization: Bearer ` ## Parameters - `ftpMonitorPublicId` (Path, required): FTP monitor public UUID. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST \ "$BASE_URL/api/ftp-monitors/55555555-5555-4555-8555-555555555555/trigger-check" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "success": true, "message": "Checks triggered successfully", "ftpMonitorId": 400, "locationCodes": ["de-nbg", "fi-hel"], "queueNames": ["ftp-monitor-checks-de-nbg", "ftp-monitor-checks-fi-hel"] } ``` ## Common Errors - `400 FTP monitor public ID (UUID) required` if `ftpMonitorPublicId` is missing or invalid - `400 No eligible monitoring locations for the selected allowed countries` if your country restrictions match no active locations - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have write access - `503 No active monitoring locations available` if no worker locations are active
### Update FTP Monitor (Change Status)
URL: https://docs.uptimeify.io/api/monitors/ftp-monitors/update-ftp-monitor
Description: Updates an FTP monitor and/or changes its status.
Summary: `PATCH /api/ftp-monitors/:ftpMonitorPublicId` ## Authentication `Authorization: Bearer ` ## Parameters - `ftpMonitorPublicId` (Path, required): FTP monitor public UUID. ## Request Body - `status` (optional): `active`, `maintenance`, `disabled` (also accepts `inactive`/`paused` and normalizes them to `disabled`) - `customerId` (optional, number): Must belong to the same organization - `name` (optional, string) - `hostname` (optional, string): Must be a hostname (no protocol, no path) - `port` (optional, number | null) - `checkInterval` (optional, number) - `timeoutSeconds` (optional, number) - `allowedCheckCountryCodes` (optional, string[] | null): ISO-3166-1 alpha-2, e.g. `"DE"`, `"ES"` - `checkMode` (optional, string): `protocol` (default) | `tcp`. Switching to `tcp` clears any stored credentials: the monitor performs a bare TCP port-reachability check and `ftpConfig` is not stored. Switching back to `protocol` re-enables the full FTP login check; supply `ftpConfig`/`config` to set new credentials. - `ftpConfig` (optional, object): Replaces the stored FTP config JSON - `config` (optional, object): Alias of `ftpConfig` Note: Read-only users may only change `status`. Note: If you omit `ftpConfig`/`config`, the current config remains unchanged. ```json { "status": "maintenance" } ``` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PATCH \ "$BASE_URL/api/ftp-monitors/55555555-5555-4555-8555-555555555555" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"status":"active","allowedCheckCountryCodes":["DE","ES"],"ftpConfig":{"user":"monitor","password":"","secure":false}}' ``` ## Response ```json { "id": 400, "status": "maintenance", "config": {}, "ftpConfig": {} } ``` ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `name` is not a non-empty string of at most 255 characters, or `allowedCheckCountryCodes` is neither an array of country codes nor `null` - `400 Bad Request` (`invalidTimeoutSeconds`) if `timeoutSeconds` is not an integer between 1 and 60 - `400 Bad Request` (`invalidConfig`) if a config field (`config`, or the type-specific one) is not an object - `400 Invalid status` if `status` is not valid - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have write access (e.g. read-only user tries to change other fields, or global supporter) - `404 FTP monitor not found` if the monitor does not exist
### ICMP Monitors
URL: https://docs.uptimeify.io/api/monitors/icmp-monitors
Description: Manage ICMP (ping) monitors.
Summary: Path-based ICMP monitor endpoints use `icmpMonitorPublicId` UUIDs. ## Endpoints - [List ICMP Monitors](/api/monitors/icmp-monitors/list-icmp-monitors) - [Create ICMP Monitor](/api/monitors/icmp-monitors/create-icmp-monitor) - [Get ICMP Monitor](/api/monitors/icmp-monitors/get-icmp-monitor) - [Get ICMP Monitor Details](/api/monitors/icmp-monitors/get-icmp-monitor-details) - [Get ICMP Monitor Check History](/api/monitors/icmp-monitors/get-icmp-monitor-check-history) - [Update ICMP Monitor](/api/monitors/icmp-monitors/update-icmp-monitor) - [Delete ICMP Monitor](/api/monitors/icmp-monitors/delete-icmp-monitor) - [Trigger ICMP Check](/api/monitors/icmp-monitors/trigger-check-icmp-monitor)
### Create ICMP Monitor
URL: https://docs.uptimeify.io/api/monitors/icmp-monitors/create-icmp-monitor
Description: Creates a new ICMP monitor.
Summary: `POST /api/icmp-monitors` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Request Body ```json { "customerId": "6764e84f-f02a-43e6-a46d-cecaec556723", "name": "Ping Gateway", "hostname": "claas.sh", "status": "active", "checkInterval": 5, "timeoutSeconds": 10, "icmpConfig": { "packetSize": 56, "count": 4 } } ``` ### Fields - `customerId` (number | string, required) - Accepts the internal numeric customer ID or the customer `publicId` UUID. - `name` (string, required) - `hostname` (string, required) - Must be a hostname or IP only (no protocol like `https://`, no path like `/ping`). - `status` (string, optional) - Allowed: `active`, `maintenance`, `disabled`, `paused`, `inactive` - Note: `paused` / `inactive` are normalized to `disabled`. - `checkInterval` (number, optional) - `timeoutSeconds` (number, optional) - `icmpConfig` (object, optional) - Stored as the monitor's `config` JSON. ### `icmpConfig` (worker-supported keys) - `packetSize` (number) - Default: `56` - `count` (number) - Default: `3` ### Duplicates If this customer already has a monitor with the same `hostname` (case and a trailing dot do not count), the request is refused with `409` and `data.code` `monitorAlreadyExists`. `data.existingId` and `data.existingPublicId` name the existing monitor. Send `"allowDuplicate": true` to create the second monitor anyway (for example with a different interval or other alert channels). - `allowDuplicate` (boolean, optional, default `false`): create the monitor even if it is a duplicate. Not stored. ```json { "statusCode": 409, "statusMessage": "A monitor for this target already exists for this customer. Send allowDuplicate: true to create it anyway.", "data": { "code": "monitorAlreadyExists", "existingId": 300, "existingPublicId": "44444444-4444-4444-8444-444444444444" } } ``` ### Limit per target host An organization can have at most 100 monitors for the same target host, counted across all monitor types together (websites with HTTP, keyword, DNS website and Playwright with a real URL, plus TCP, ICMP, DNS, SSH, SMTP, FTP and IMAP/POP). The limit protects against the check fleet being misused as a load generator against third-party hosts. The exact hostname is compared: case, port, path and a trailing dot do not count, but `www.example.com` and `example.com` are different hosts. Once the limit is reached, the request is refused with `403` and `data.code` `targetHostMonitorLimitReached`. `data.host` names the normalized host, `data.limit` the limit. `"allowDuplicate": true` does not lift the limit. The same check runs when a PATCH changes the `hostname`. A PATCH that keeps the host always succeeds, and existing monitors above the limit stay in place. If you need a higher limit, contact support. Independently of your organization, at most 300 monitors across all Uptimeify customers may target the same host. Beyond that, the request is refused with `403` and `data.code` `targetHostPlatformLimitReached`; `data.host` and `data.limit` are set as above, and the message does not reveal how many monitors other organizations have. ```json { "statusCode": 403, "statusMessage": "Target host monitor limit reached: your organization already has 100 monitors for example.com (maximum 100 per host). Remove monitors for this host or contact support to raise the limit.", "data": { "code": "targetHostMonitorLimitReached", "host": "example.com", "limit": 100 } } ``` ## cURL ```bash curl -X POST "https://YOUR_DOMAIN/api/icmp-monitors" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customerId": "6764e84f-f02a-43e6-a46d-cecaec556723", "name": "Ping Gateway", "hostname": "claas.sh", "status": "active", "checkInterval": 5, "timeoutSeconds": 10, "icmpConfig": { "packetSize": 56, "count": 4 } }' ``` ## Response ```json { "id": 123, "organizationId": 1, "customerId": 2, "name": "Ping Gateway", "hostname": "claas.sh", "port": null, "status": "active", "checkInterval": 5, "timeout…
### Delete ICMP Monitor
URL: https://docs.uptimeify.io/api/monitors/icmp-monitors/delete-icmp-monitor
Description: Deletes an ICMP monitor.
Summary: `DELETE /api/icmp-monitors/:icmpMonitorPublicId` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `icmpMonitorPublicId` (Path, required): ICMP monitor public UUID. ## cURL ```bash curl -X DELETE "https://YOUR_DOMAIN/api/icmp-monitors/22222222-2222-4222-8222-222222222222" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "success": true } ``` ## Errors - `400` ICMP monitor public ID (UUID) required - `401` Unauthorized - `403` Forbidden (`readonlyMayNotDelete` for a read-only caller, `managed_by_organization` for a managed resource without `canEditManaged`) - `404` ICMP monitor not found ## Permissions Closed to the `readonly` role. A read-only login deletes no monitor, whatever its ownership class, and neither does an API token it issued: a token inherits the role of the user who created it. Editing a `self_service` monitor stays open to that role. A customer-scoped caller is bound by ownership class on top of that: a `managed` monitor is refused with `managed_by_organization` unless its customer carries `canEditManaged`.
### Get ICMP Monitor
URL: https://docs.uptimeify.io/api/monitors/icmp-monitors/get-icmp-monitor
Description: Returns details of a specific ICMP monitor.
Summary: `GET /api/icmp-monitors/:icmpMonitorPublicId` The response contains the ICMP monitor itself and does not embed the full customer record. ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `icmpMonitorPublicId` (Path, required): ICMP monitor public UUID. ## cURL ```bash curl "https://YOUR_DOMAIN/api/icmp-monitors/22222222-2222-4222-8222-222222222222" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "id": 123, "organizationId": 1, "customerId": 10, "name": "Core Router", "hostname": "10.0.0.1", "port": null, "status": "active", "checkInterval": 30, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE"], "config": { "packetSize": 56, "count": 3 }, "notificationPhoneNumber": null, "notificationEmail": null, "lastCheckedAt": null, "createdAt": "2026-02-26T12:00:00.000Z", "updatedAt": "2026-02-26T12:00:00.000Z", "icmpConfig": { "packetSize": 56, "count": 3 } } ``` ## Errors - `400` ICMP monitor public ID (UUID) required - `401` Unauthorized - `404` ICMP monitor not found when the monitor does not exist **or belongs to another customer or organization** (the two cases are indistinguishable on purpose)
### Get ICMP Monitor Alert History
URL: https://docs.uptimeify.io/api/monitors/icmp-monitors/get-icmp-monitor-alert-history
Description: Returns notification/escalation attempts (alert history) for incidents of a ICMP monitor.
Summary: `GET /api/icmp-monitors/:icmpMonitorPublicId/alert-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `icmpMonitorPublicId` (Path, required): ICMP monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). - `limit` (number, optional): Items per page (default: `25`; max `100`). Ignored in favor of export defaults when `format=csv` or `download=1` (default `10000`, max `50000`). - `status` (string, optional): `sent` or `failed`. - `from` / `to` (ISO date string, optional): Filter by `sentAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` to force an attachment download, `0` (default) for the page. - `envelope` (string, optional): `items` answers as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/icmp-monitors/11111111-1111-4111-8111-111111111111/alert-history?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [ { "id": 987, "incidentId": 123, "type": "slack", "status": "sent", "channelName": "Ops Slack", "channelType": "slack", "channelConfig": null, "sentAt": "2026-02-26T12:11:00.000Z", "errorMessage": null } ], "total": 1, "page": 1, "perPage": 25 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }` (`perPage` is the `limit`). Without it the endpoint still answers the current form `{ data, total, page, pageCount }`, which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. Each entry is one delivery attempt to one notification channel. `status` is `sent` or `failed` (with `errorMessage` set on failure); `channelType` is the channel type (e.g. `email`, `slack`, `opsgenie`). `channelConfig` has secrets redacted. When `format=csv` (or `download=1`), the response is a `text/csv` (or `application/json` for `format=json&download=1`) attachment instead of the paginated JSON list above. ## Common Errors - `400 ICMP monitor public ID (UUID) required` if `:icmpMonitorPublicId` is invalid - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the monitor
### Get ICMP Monitor Check History
URL: https://docs.uptimeify.io/api/monitors/icmp-monitors/get-icmp-monitor-check-history
Description: Returns recent check results for the ICMP monitor.
Summary: `GET /api/icmp-monitors/:icmpMonitorPublicId/check-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `icmpMonitorPublicId` (Path, required): ICMP monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). A page counts check cycles, not rows: one cycle has one row per location. - `limit` (number, optional): Cycles per page (default: `10`; max `100`). With `format=csv` or `download=1` the export defaults apply instead (default `10000`, max `50000` rows). - `status` (string, optional): `success` or `failure` (`failure` also matches `timeout`). On minute rows: no failed location, or at least one. - `minMs` / `maxMs` (number, optional): Filter by response time range (`timingTotal`; on minute rows the minute average). - `from` / `to` (ISO date string, optional): Filter by `checkedAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` forces an attachment download. ## cURL ```bash curl "https://YOUR_DOMAIN/api/icmp-monitors/44444444-4444-4444-8444-444444444444/check-history?page=1&limit=10" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "data": [ { "id": "33c53ac4-a2bc-475c-a904-8d3d6aab2979", "status": "success", "success": true, "errorMessage": null, "checkedAt": "2026-10-01T05:40:55.690Z", "responseTimeMs": 29, "location": { "name": "Paris (FR)", "code": "par" }, "resolution": "raw" }, { "id": "1min-2026-09-30T15:55:00.000Z", "status": "success", "success": true, "errorMessage": null, "checkedAt": "2026-09-30T15:55:00.000Z", "responseTimeMs": 54, "location": null, "resolution": "1min", "totalLocations": 2, "failedLocations": 0 } ], "total": 864, "page": 17, "pageCount": 87, "resolution": "mixed", "rawWindowFrom": "2026-09-30T16:00:00.000Z" } ``` - `resolution` per row: `raw` is a single check with location and error message; `1min` is one minute across all locations, without location or error message, with `totalLocations` and `failedLocations`. - `resolution` of the page: `raw`, `1min` or `mixed` (the page spans the boundary). - `rawWindowFrom`: where individual checks begin; older rows are minute rows. With `format=csv` (or `download=1`) the response is a `text/csv` attachment (or `application/json` for `format=json&download=1`) instead of the paginated JSON above. CSV columns: `checkedAt,status,responseTimeMs,location,errorMessage,resolution`. ## Data retention Individual checks, with location and error message, are kept for 24 hours. Older entries come from minute aggregates (30 days), one row per minute without location or error message. Daily figures (24 months) are available through the monitor details. ## Errors - `400` ICMP monitor public ID (UUID) required - `401` Unauthorized - `403` Forbidden - `404` ICMP monitor not found ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status`, `minMs` or `maxMs` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date
### Get ICMP Monitor Details
URL: https://docs.uptimeify.io/api/monitors/icmp-monitors/get-icmp-monitor-details
Description: Returns a consolidated payload used by the monitor details page, including the monitor, customer, and aggregated check data for a given time range.
Summary: `GET /api/icmp-monitors/:icmpMonitorPublicId/details` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `icmpMonitorPublicId` (Path, required): ICMP monitor public UUID. ### Time range query parameters The endpoint supports multiple ways to define the time range. Use the simplest option for your use case: - `range` (Query, optional): Preset range. - Allowed: `day` (default), `week`, `month`, `year` - `date` (Query, optional): Reference date used as the default end date. - Example: `2026-02-26` - `startDate` (Query, optional): Start date/time. - `endDate` (Query, optional): End date/time. - `granularity` (Query, optional): Controls aggregation. - Use `raw` to disable aggregation. - Any other value enables aggregation. - If omitted, the server may aggregate automatically for larger ranges. If you provide multiple, the server resolves them according to its internal precedence rules. ## cURL ```bash curl -X GET "https://YOUR_DOMAIN/api/icmp-monitors/22222222-2222-4222-8222-222222222222/details?range=day&granularity=raw" \ -H "Authorization: Bearer $TOKEN" ``` ## Response Top-level fields (current shape): - `icmpMonitorId` - `monitor` - `latestCheck` - `uptimeStats`, `uptimeStatsMeta` - `monitoringData` - `incidents` - `alerts` - `testResultLog` - `maintenance` Example: ```json { "icmpMonitorId": 123, "monitor": { "id": 123, "customerId": 10, "organizationId": 1, "name": "Core Router", "hostname": "10.0.0.1", "status": "active", "checkInterval": 30, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE"], "port": null, "config": { "packetSize": 56, "count": 3 }, "notificationPhoneNumber": null, "notificationEmail": null, "lastCheckedAt": null, "createdAt": "2026-02-26T12:00:00.000Z", "updatedAt": "2026-02-26T12:00:00.000Z" }, "latestCheck": null, "uptimeStats": { "day": "100.00", "month": "100.00", "year": "100.00", "dayAvgResponse": 22, "monthAvgResponse": 22, "yearAvgResponse": 22 }, "uptimeStatsMeta": { "day": { "window": "24h", "downtimeMinutes": 0, "incidents": 0, "checksTotal": 24, "checksFailed": 0 }, "month": { "window": "30d", "downtimeMinutes": 0, "incidents": 0, "checksTotal": 720, "checksFailed": 0 }, "year": { "window": "YTD", "downtimeMinutes": 0, "incidents": 0, "checksTotal": 1000, "checksFailed": 0 } }, "monitoringData": { "responseTimeData": [ { "timestamp": "2026-02-26T12:00:00.000Z", "responseTime": 22, "status": "success", "success": true, "timingDns": 0, "timingTcp": 22, "timingTls": 0, "timingTtfb": 0, "timingTransfer": 0 } ], "statusData": [{ "date": "26.02", "status": "online" }], "uptimePercentage": "100.00", "checkSuccessRatePercentage": "100.00", "totalChecks": 100, "successfulChecks": 100 }, "incidents": { "history": [], "total": 0, "ongoing": 0, "totalDowntime": "0s" }, "alerts": { "history": [], "total": 0, "notificationContext": { "orgDefaultEmail": null, "orgDefaultPhoneNumber": null, "customerEmail": null, "notificationTargets": [] } }, "testResultLog": [], "maintenance": { "inMaintenance": false, "activeWindows": [], "allWindows": [] } } ``` ## Data retention Single checks are kept for 24 hours, minute aggregates for 30 days and daily aggregates for 24 months; a range older than 30 days returns one point per day. If the monitor has no check within the last 24 hours, `latestCheck` describes its last minute from the aggregate: `id` starts with `1min-`, `resolution` is `1min`, and `locationId` and `errorMessage` are `null`. ## Errors - `400` ICMP monitor public ID (UUID) required - `401` Unauthorized - `403` Forbidden - `404` ICMP monitor not found - `500` Failed to fetch ICMP monitor details ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `range` is not `day`/`week`/`month`/`year`, `date`/`startDate`/`endDate` is not a date, only one of `startDate`/`endDate` is given, `tz` is not an integer, or `granularity` is not `raw`/`aggregated`
### Get ICMP Monitor Incident History
URL: https://docs.uptimeify.io/api/monitors/icmp-monitors/get-icmp-monitor-incident-history
Description: Returns incidents for a single ICMP monitor (latest 100), including a computed duration.
Summary: `GET /api/icmp-monitors/:icmpMonitorPublicId/incident-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `icmpMonitorPublicId` (Path, required): ICMP monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). - `limit` (number, optional): Items per page (default: `25`; max `100`). Ignored in favor of export defaults when `format=csv` or `download=1` (default `10000`, max `50000`). - `status` (string, optional): `open`, `acknowledged`, or `resolved`. - `type` (string, optional): `downtime`, `http_status`, `ssl_expiry`, `ssl_critical`, `ssl_warning`, `response_time`, `dnsbl`, `domain_expiry_warning`, `critical`, or `inconclusive`. - `from` / `to` (ISO date string, optional): Filter by `startedAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` to force an attachment download, `0` (default) for the page. - `envelope` (string, optional): `items` answers as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/icmp-monitors/11111111-1111-4111-8111-111111111111/incident-history?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [ { "id": 123, "publicId": "55555555-5555-4555-8555-555555555555", "type": "downtime", "status": "resolved", "startedAt": "2026-02-26T12:10:00.000Z", "endedAt": "2026-02-26T12:12:30.000Z", "durationMs": 150000, "statusCode": null, "errorMessage": "connect ETIMEDOUT", "details": "connect ETIMEDOUT", "isOngoing": false } ], "total": 1, "page": 1, "perPage": 25 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }` (`perPage` is the `limit`). Without it the endpoint still answers the current form `{ data, total, page, pageCount }`, which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. **Deprecated field:** `duration` (text, e.g. `2m 30s`) is still sent next to `durationMs` until it is removed on 2027-01-18. Read `durationMs`. `status` is `open`, `acknowledged`, or `resolved`. Ongoing incidents have a `null` `endedAt` and `isOngoing: true`. When `format=csv` (or `download=1`), the response is a `text/csv` (or `application/json` for `format=json&download=1`) attachment instead of the paginated JSON list above. ## Common Errors - `400 ICMP monitor public ID (UUID) required` if `:icmpMonitorPublicId` is invalid - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status` or `type` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the monitor
### List ICMP Monitors
URL: https://docs.uptimeify.io/api/monitors/icmp-monitors/list-icmp-monitors
Description: Lists ICMP monitors in an organization.
Summary: `GET /api/icmp-monitors` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `organizationId` (Query, optional): Organization ID. Defaults to the current user's organization. - `customerId` (Query, optional): Filter by customer ID. - `search` (Query, optional): Search by monitor name, hostname, or customer. - `page` (Query, optional): Page number (default: 1). - `perPage` (Query, optional): Items per page (default: 50, max: 200). ## cURL ```bash curl "https://YOUR_DOMAIN/api/icmp-monitors?page=1&perPage=50" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "items": [ { "id": 123, "organizationId": 1, "customerId": 10, "customerName": "Example Customer", "name": "Core Router", "hostname": "10.0.0.1", "status": "active", "checkInterval": 30, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE"], "port": null, "config": { "packetSize": 56, "count": 3 }, "notificationPhoneNumber": null, "notificationEmail": null, "lastCheckedAt": null, "createdAt": "2026-02-26T12:00:00.000Z", "updatedAt": "2026-02-26T12:00:00.000Z" } ], "total": 1, "page": 1, "perPage": 50 } ``` Each item contains the ICMP monitor itself and a flat `customerName`, not a full embedded customer record. ## Inline metrics Every item carries the same rolled-up metrics the other monitor list endpoints return. They are computed per monitor over the calendar day, month and year in UTC. | Field | Type | Meaning | |------|-----|---------| | `uptimeDay` / `uptimeMonth` / `uptimeYear` | string | Uptime percentage with two decimals, e.g. `"99.94"` | | `avgResponseDay` / `avgResponseMonth` / `avgResponseYear` | number \| null | Average response time in milliseconds; `null` when nothing was measured in that window | | `responseGraph` | object | `{ values, avg }` for the last 24 hours, one entry per hour; an hour with no successful check is `null` | | `upSinceAt` | string \| null | ISO timestamp the monitor has been up since, `null` while it is down | | `isDown` | boolean | Whether the monitor is currently in an unresolved incident | The day figures are read from the raw check data, the month and year from continuous aggregates, so a value may lag the newest check by a few minutes in the month and year windows. ## Errors - `400` Invalid query parameters (e.g. `organizationId`, `customerId`) - `401` Unauthorized - `403` Forbidden ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `page` or `perPage` is not a positive integer, `sortOrder` is not `asc`/`desc`, or `tags` is not a comma-separated list of tag ids
### Trigger ICMP Check
URL: https://docs.uptimeify.io/api/monitors/icmp-monitors/trigger-check-icmp-monitor
Description: Triggers an immediate check from all eligible monitoring locations.
Summary: `POST /api/icmp-monitors/:icmpMonitorPublicId/trigger-check` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `icmpMonitorPublicId` (Path, required): ICMP monitor public UUID. ## cURL ```bash curl -X POST "https://YOUR_DOMAIN/api/icmp-monitors/22222222-2222-4222-8222-222222222222/trigger-check" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "success": true, "message": "Checks triggered successfully", "icmpMonitorId": 123, "locationCodes": ["de-nbg", "fi-hel"], "queueNames": ["icmp-monitor-checks-de-nbg", "icmp-monitor-checks-fi-hel"] } ``` ## Errors - `400` ICMP monitor public ID (UUID) required or no eligible locations - `401` Unauthorized - `403` Forbidden - `404` ICMP monitor not found - `503` No active monitoring locations available - `500` Failed to trigger check
### Update ICMP Monitor
URL: https://docs.uptimeify.io/api/monitors/icmp-monitors/update-icmp-monitor
Description: Updates an ICMP monitor. This endpoint is also used to change the monitor status.
Summary: `PATCH /api/icmp-monitors/:icmpMonitorPublicId` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `icmpMonitorPublicId` (Path, required): ICMP monitor public UUID. ## Request Body All fields are optional. - `status` (optional) - Allowed: `active`, `maintenance`, `disabled`, `paused`, `inactive` - Note: `paused` / `inactive` are normalized to `disabled`. - `name`, `hostname`, `checkInterval`, `timeoutSeconds` (optional) - `port` (optional) - Supported by the API, but currently not used by the ICMP worker. - `allowedCheckCountryCodes` (optional) - Normalized to upper-case and de-duplicated. - `icmpConfig` (optional) - Alias for the stored `config` JSON. - `config` (optional) - Alternative way to update the same stored `config` JSON. Note: Read-only users may only change `status` (and sending any other fields will result in `403`). ```json { "status": "maintenance", "allowedCheckCountryCodes": ["DE", "ES"] } ``` Example updating config: ```json { "icmpConfig": { "packetSize": 56, "count": 3 } } ``` ## cURL ```bash curl -X PATCH "https://YOUR_DOMAIN/api/icmp-monitors/22222222-2222-4222-8222-222222222222" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "disabled" }' ``` ## Response ```json { "id": 123, "organizationId": 1, "customerId": 10, "name": "Core Router", "hostname": "10.0.0.1", "port": null, "status": "maintenance", "checkInterval": 30, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE", "ES"], "notificationPhoneNumber": null, "notificationEmail": null, "lastCheckedAt": null, "createdAt": "2026-02-26T12:00:00.000Z", "updatedAt": "2026-02-26T12:05:00.000Z", "config": { "packetSize": 56, "count": 3 }, "icmpConfig": { "packetSize": 56, "count": 3 } } ``` ## Errors - `400` Invalid request body, invalid status, or invalid hostname - `401` Unauthorized - `403` Forbidden (e.g. `readonly` or global supporter) - `404` ICMP monitor not found ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `name` is not a non-empty string of at most 255 characters, or `allowedCheckCountryCodes` is neither an array of country codes nor `null` - `400 Bad Request` (`invalidTimeoutSeconds`) if `timeoutSeconds` is not an integer between 1 and 60 - `400 Bad Request` (`invalidConfig`) if a config field (`config`, or the type-specific one) is not an object
### IMAP/POP Monitors
URL: https://docs.uptimeify.io/api/monitors/imap-pop-monitors
Description: Manage IMAP/POP monitors.
Summary: Path-based IMAP/POP monitor endpoints use `imapPopMonitorPublicId` UUIDs. ## Endpoints - [List IMAP/POP Monitors](/api/monitors/imap-pop-monitors/list-imap-pop-monitors) - [Create IMAP/POP Monitor](/api/monitors/imap-pop-monitors/create-imap-pop-monitor) - [Get IMAP/POP Monitor](/api/monitors/imap-pop-monitors/get-imap-pop-monitor) - [Update IMAP/POP Monitor](/api/monitors/imap-pop-monitors/update-imap-pop-monitor) - [Delete IMAP/POP Monitor](/api/monitors/imap-pop-monitors/delete-imap-pop-monitor) - [Trigger IMAP/POP Check](/api/monitors/imap-pop-monitors/trigger-check-imap-pop-monitor) - [Get IMAP/POP Monitor Details](/api/monitors/imap-pop-monitors/get-imap-pop-monitor-details) - [Get IMAP/POP Monitor Check History](/api/monitors/imap-pop-monitors/get-imap-pop-monitor-check-history)
### Create IMAP/POP Monitor
URL: https://docs.uptimeify.io/api/monitors/imap-pop-monitors/create-imap-pop-monitor
Description: Creates a new IMAP/POP monitor.
Summary: `POST /api/imap-pop-monitors` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Request Body ```json { "customerId": "11111111-1111-4111-8111-111111111111", "name": "Mailbox Access", "hostname": "mail.deinkunde.com", "port": 993, "status": "active", "checkInterval": 30, "timeoutSeconds": 30, "imapPopConfig": { "protocol": "imap", "user": "monitor@deinkunde.com", "password": "password", "tls": true, "tlsOptions": { "rejectUnauthorized": true } } } ``` ### Fields - `customerId` (number | string, required) - Accepts either the internal numeric customer ID or the public customer UUID. - `name` (string, required) - `hostname` (string, required) - Must be a hostname only (no protocol like `https://`, no path like `/imap`). - `port` (number | null, optional) - If omitted or `null`, the worker chooses a default port depending on `imapPopConfig.protocol` and `imapPopConfig.tls`. - `status` (string, optional) - Allowed: `active`, `maintenance`, `disabled`, `paused`, `inactive` - Note: `paused` / `inactive` are normalized to `disabled`. - `checkInterval` (number, optional) - `timeoutSeconds` (number, optional) - `checkMode` (string, optional) - Allowed: `protocol`, `tcp`. Defaults to `protocol`. - In `tcp` mode the monitor performs a bare TCP port-reachability check: `imapPopConfig` is not required and is not stored. In `protocol` mode the full IMAP/POP login check runs (existing behavior). - **`port` is required when `checkMode` is `tcp`**. Without it the request fails with `400` / `data.code: "portRequiredForTcp"`. - `imapPopConfig` (object, optional) - Stored as the monitor's `config` JSON. - Required (`user` + `password`) unless `checkMode` is `tcp`. ### `imapPopConfig` (worker-supported keys) - `protocol` (`imap` | `pop3`) - Default: `imap` - `user` (string) - `password` (string) - `tls` (boolean) - Default: `false` - `tlsOptions.rejectUnauthorized` (boolean) - Used by the IMAP worker library; POP3 currently ignores this option. ### Default ports (worker behavior) If `port` is omitted or `null`: - IMAP: - TLS (`tls: true`): `993` - Non-TLS (`tls: false`): `143` - POP3: - TLS (`tls: true`): `995` - Non-TLS (`tls: false`): `110` ### Duplicates If this customer already has a monitor with the same `hostname` (case and a trailing dot do not count), `port`, `checkMode` and `imapPopConfig.protocol`, the request is refused with `409` and `data.code` `monitorAlreadyExists`. `data.existingId` and `data.existingPublicId` name the existing monitor. Send `"allowDuplicate": true` to create the second monitor anyway (for example with a different interval or other alert channels). - `allowDuplicate` (boolean, optional, default `false`): create the monitor even if it is a duplicate. Not stored. ```json { "statusCode": 409, "statusMessage": "A monitor for this target already exists for this customer. Send allowDuplicate: true to create it anyway.", "data": { "code": "monitorAlreadyExists", "existingId": 300, "existingPublicId": "44444444-4444-4444-8444-444444444444" } } ``` ### Limit per target host An organization can have at most 100 monitors for the same target host, counted across all monitor types together (websites with HTTP, keyword, DNS website and Playwright with a real URL, plus TCP, ICMP, DNS, SSH, SMTP, FTP and IMAP/POP). The limit protects against the check fleet being misused as a load generator against third-party hosts. The exact hostname is compared: case, port, path and a trailing dot do not count, but `www.example.com` and `example.com` are different hosts. Once the limit is reached, the request is refused with `403` and `data.code` `targetHostMonitorLimitReached`. `data.host` names the normalized host, `data.limit` the limit. `"allowDuplicate": true` does not lift the limit. The same check runs when a PATCH changes the `hostname`. A PATCH that keeps the host always succeeds, and existing monitors above the limit stay in place. If you need a higher limit, contact support. Independently of your…
### Delete IMAP/POP Monitor
URL: https://docs.uptimeify.io/api/monitors/imap-pop-monitors/delete-imap-pop-monitor
Description: Deletes an IMAP/POP monitor.
Summary: `DELETE /api/imap-pop-monitors/:imapPopMonitorPublicId` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `imapPopMonitorPublicId` (Path, required): IMAP/POP monitor public UUID. ## Response ```json { "success": true } ``` ## Errors - `400` IMAP/POP monitor public ID (UUID) required - `401` Unauthorized - `403` Forbidden (e.g. `readonly` or global supporter) - `404` IMAP/POP monitor not found ## Permissions Closed to the `readonly` role. A read-only login deletes no monitor, whatever its ownership class, and neither does an API token it issued: a token inherits the role of the user who created it. Editing a `self_service` monitor stays open to that role. A customer-scoped caller is bound by ownership class on top of that: a `managed` monitor is refused with `managed_by_organization` unless its customer carries `canEditManaged`.
### Get IMAP/POP Monitor
URL: https://docs.uptimeify.io/api/monitors/imap-pop-monitors/get-imap-pop-monitor
Description: Returns details of a specific IMAP/POP monitor.
Summary: `GET /api/imap-pop-monitors/:imapPopMonitorPublicId` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `imapPopMonitorPublicId` (Path, required): IMAP/POP monitor public UUID. ## Response ```json { "id": 500, "organizationId": 1, "customerId": 10, "name": "Mailbox Access", "hostname": "mail.deinkunde.com", "port": 993, "checkInterval": 30, "timeoutSeconds": 30, "config": { "protocol": "imap", "user": "monitor@deinkunde.com", "password": "password", "tls": true }, "allowedCheckCountryCodes": null, "status": "active", "notificationPhoneNumber": null, "notificationEmail": null, "lastCheckedAt": null, "createdAt": "2026-02-26T12:00:00.000Z", "updatedAt": "2026-02-26T12:00:00.000Z", "customer": { "id": 10, "organizationId": 1, "name": "Example Customer", "email": "ops@deinkunde.com", "allowedCheckCountryCodes": null, "customFields": null, "alertLocationThresholdCount": 1, "createdAt": "2026-02-01T12:00:00.000Z", "updatedAt": "2026-02-01T12:00:00.000Z" }, "imapPopConfig": { "protocol": "imap", "user": "monitor@deinkunde.com", "password": "password", "tls": true } } ``` ## Errors - `400` IMAP/POP monitor public ID (UUID) required - `401` Unauthorized - `404` IMAP/POP monitor not found when the monitor does not exist **or belongs to another customer or organization** (the two cases are indistinguishable on purpose)
### Get IMAP/POP Monitor Alert History
URL: https://docs.uptimeify.io/api/monitors/imap-pop-monitors/get-imap-pop-monitor-alert-history
Description: Returns notification/escalation attempts (alert history) for incidents of a IMAP/POP monitor.
Summary: `GET /api/imap-pop-monitors/:imapPopMonitorPublicId/alert-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `imapPopMonitorPublicId` (Path, required): IMAP/POP monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). - `limit` (number, optional): Items per page (default: `25`; max `100`). Ignored in favor of export defaults when `format=csv` or `download=1` (default `10000`, max `50000`). - `status` (string, optional): `sent` or `failed`. - `from` / `to` (ISO date string, optional): Filter by `sentAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` to force an attachment download, `0` (default) for the page. - `envelope` (string, optional): `items` answers as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/imap-pop-monitors/11111111-1111-4111-8111-111111111111/alert-history?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [ { "id": 987, "incidentId": 123, "type": "slack", "status": "sent", "channelName": "Ops Slack", "channelType": "slack", "channelConfig": null, "sentAt": "2026-02-26T12:11:00.000Z", "errorMessage": null } ], "total": 1, "page": 1, "perPage": 25 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }` (`perPage` is the `limit`). Without it the endpoint still answers the current form `{ data, total, page, pageCount }`, which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. Each entry is one delivery attempt to one notification channel. `status` is `sent` or `failed` (with `errorMessage` set on failure); `channelType` is the channel type (e.g. `email`, `slack`, `opsgenie`). `channelConfig` has secrets redacted. When `format=csv` (or `download=1`), the response is a `text/csv` (or `application/json` for `format=json&download=1`) attachment instead of the paginated JSON list above. ## Common Errors - `400 IMAP/POP monitor public ID (UUID) required` if `:imapPopMonitorPublicId` is invalid - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the monitor
### Get IMAP/POP Monitor Check History
URL: https://docs.uptimeify.io/api/monitors/imap-pop-monitors/get-imap-pop-monitor-check-history
Description: Returns recent check results for the IMAP/POP monitor.
Summary: `GET /api/imap-pop-monitors/:imapPopMonitorPublicId/check-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `imapPopMonitorPublicId` (Path, required): IMAP/POP monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). A page counts check cycles, not rows: one cycle has one row per location. - `limit` (number, optional): Cycles per page (default: `10`; max `100`). With `format=csv` or `download=1` the export defaults apply instead (default `10000`, max `50000` rows). - `status` (string, optional): `success` or `failure` (`failure` also matches `timeout`). On minute rows: no failed location, or at least one. - `minMs` / `maxMs` (number, optional): Filter by response time range (`timingTotal`; on minute rows the minute average). - `from` / `to` (ISO date string, optional): Filter by `checkedAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` forces an attachment download. ## cURL ```bash curl "https://YOUR_DOMAIN/api/imap-pop-monitors/44444444-4444-4444-8444-444444444444/check-history?page=1&limit=10" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "data": [ { "id": "33c53ac4-a2bc-475c-a904-8d3d6aab2979", "status": "success", "success": true, "errorMessage": null, "checkedAt": "2026-10-01T05:40:55.690Z", "responseTimeMs": 29, "location": { "name": "Paris (FR)", "code": "par" }, "resolution": "raw" }, { "id": "1min-2026-09-30T15:55:00.000Z", "status": "success", "success": true, "errorMessage": null, "checkedAt": "2026-09-30T15:55:00.000Z", "responseTimeMs": 54, "location": null, "resolution": "1min", "totalLocations": 2, "failedLocations": 0 } ], "total": 864, "page": 17, "pageCount": 87, "resolution": "mixed", "rawWindowFrom": "2026-09-30T16:00:00.000Z" } ``` - `resolution` per row: `raw` is a single check with location and error message; `1min` is one minute across all locations, without location or error message, with `totalLocations` and `failedLocations`. - `resolution` of the page: `raw`, `1min` or `mixed` (the page spans the boundary). - `rawWindowFrom`: where individual checks begin; older rows are minute rows. With `format=csv` (or `download=1`) the response is a `text/csv` attachment (or `application/json` for `format=json&download=1`) instead of the paginated JSON above. CSV columns: `checkedAt,status,responseTimeMs,location,errorMessage,resolution`. ## Data retention Individual checks, with location and error message, are kept for 24 hours. Older entries come from minute aggregates (30 days), one row per minute without location or error message. Daily figures (24 months) are available through the monitor details. ## Errors - `400` IMAP/POP monitor public ID (UUID) required - `401` Unauthorized - `403` Forbidden - `404` IMAP/POP monitor not found ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status`, `minMs` or `maxMs` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date
### Get IMAP/POP Monitor Details
URL: https://docs.uptimeify.io/api/monitors/imap-pop-monitors/get-imap-pop-monitor-details
Description: Consolidated endpoint that returns the IMAP/POP monitor detail page payload in a single call (latest check, uptime stats, incidents, alert history, maintenance windows, chart data, etc.).
Summary: `GET /api/imap-pop-monitors/:imapPopMonitorPublicId/details` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `imapPopMonitorPublicId` (Path, required): IMAP/POP monitor public UUID. - `range` (Query, optional): `day` | `week` | `month` | `year` (default: `day`). - `date` (Query, optional): Reference date as ISO string. - `startDate` (Query, optional): Override start date as ISO string. - `endDate` (Query, optional): Override end date as ISO string. - `granularity` (Query, optional): If set and not `raw`, the backend may aggregate monitoring chart data. ## cURL ```bash curl -X GET "https://YOUR_DOMAIN/api/imap-pop-monitors/66666666-6666-4666-8666-666666666666/details?range=day" \ -H "Authorization: Bearer $TOKEN" ``` ## Response The response is a large object. Key top-level fields: - `imapPopMonitorId` - `monitor` - `latestCheck` - `uptimeStats`, `uptimeStatsMeta` - `monitoringData` - `incidents` - `alerts` - `testResultLog` - `maintenance` Example (truncated): ```json { "imapPopMonitorId": 500, "monitor": { "id": 500, "hostname": "mail.deinkunde.com", "status": "active" }, "latestCheck": { "id": 123, "status": "success", "checkedAt": "2026-02-26T12:00:00.000Z" }, "uptimeStats": { "day": "100.00", "month": "100.00", "year": "100.00", "dayAvgResponse": 142, "monthAvgResponse": 150, "yearAvgResponse": 160 }, "maintenance": { "inMaintenance": false, "activeWindows": [], "allWindows": [] } } ``` ## Data retention Single checks are kept for 24 hours, minute aggregates for 30 days and daily aggregates for 24 months; a range older than 30 days returns one point per day. If the monitor has no check within the last 24 hours, `latestCheck` describes its last minute from the aggregate: `id` starts with `1min-`, `resolution` is `1min`, and `locationId` and `errorMessage` are `null`. ## Errors - `400` Invalid IMAP/POP monitor public ID (UUID) - `401` Unauthorized - `403` Forbidden - `404` IMAP/POP monitor not found - `500` Failed to fetch IMAP/POP monitor details ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `range` is not `day`/`week`/`month`/`year`, `date`/`startDate`/`endDate` is not a date, only one of `startDate`/`endDate` is given, `tz` is not an integer, or `granularity` is not `raw`/`aggregated`
### Get IMAP/POP Monitor Incident History
URL: https://docs.uptimeify.io/api/monitors/imap-pop-monitors/get-imap-pop-monitor-incident-history
Description: Returns incidents for a single IMAP/POP monitor (latest 100), including a computed duration.
Summary: `GET /api/imap-pop-monitors/:imapPopMonitorPublicId/incident-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `imapPopMonitorPublicId` (Path, required): IMAP/POP monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). - `limit` (number, optional): Items per page (default: `25`; max `100`). Ignored in favor of export defaults when `format=csv` or `download=1` (default `10000`, max `50000`). - `status` (string, optional): `open`, `acknowledged`, or `resolved`. - `type` (string, optional): `downtime`, `http_status`, `ssl_expiry`, `ssl_critical`, `ssl_warning`, `response_time`, `dnsbl`, `domain_expiry_warning`, `critical`, or `inconclusive`. - `from` / `to` (ISO date string, optional): Filter by `startedAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` to force an attachment download, `0` (default) for the page. - `envelope` (string, optional): `items` answers as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/imap-pop-monitors/11111111-1111-4111-8111-111111111111/incident-history?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [ { "id": 123, "publicId": "55555555-5555-4555-8555-555555555555", "type": "downtime", "status": "resolved", "startedAt": "2026-02-26T12:10:00.000Z", "endedAt": "2026-02-26T12:12:30.000Z", "durationMs": 150000, "statusCode": null, "errorMessage": "connect ETIMEDOUT", "details": "connect ETIMEDOUT", "isOngoing": false } ], "total": 1, "page": 1, "perPage": 25 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }` (`perPage` is the `limit`). Without it the endpoint still answers the current form `{ data, total, page, pageCount }`, which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. **Deprecated field:** `duration` (text, e.g. `2m 30s`) is still sent next to `durationMs` until it is removed on 2027-01-18. Read `durationMs`. `status` is `open`, `acknowledged`, or `resolved`. Ongoing incidents have a `null` `endedAt` and `isOngoing: true`. When `format=csv` (or `download=1`), the response is a `text/csv` (or `application/json` for `format=json&download=1`) attachment instead of the paginated JSON list above. ## Common Errors - `400 IMAP/POP monitor public ID (UUID) required` if `:imapPopMonitorPublicId` is invalid - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status` or `type` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the monitor
### List IMAP/POP Monitors
URL: https://docs.uptimeify.io/api/monitors/imap-pop-monitors/list-imap-pop-monitors
Description: Lists IMAP/POP monitors in an organization.
Summary: `GET /api/imap-pop-monitors` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `organizationId` (Query, optional): Organization ID. Defaults to the current user's organization. - `customerId` (Query, optional): Filter by customer ID. - `search` (Query, optional): Search by monitor name, hostname, or customer. - `page` (Query, optional): Page number (default: 1). - `perPage` (Query, optional): Items per page (default: 50, max: 200). ## Response ```json { "items": [ { "id": 500, "organizationId": 1, "customerId": 10, "name": "Mailbox Access", "hostname": "mail.deinkunde.com", "port": 993, "checkInterval": 30, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE"], "customerName": "Example Customer", "config": { "protocol": "imap", "user": "monitor@deinkunde.com", "password": "password", "tls": true }, "status": "active", "notificationPhoneNumber": null, "notificationEmail": null, "lastCheckedAt": null, "createdAt": "2026-02-26T12:00:00.000Z", "updatedAt": "2026-02-26T12:00:00.000Z" } ], "total": 1, "page": 1, "perPage": 50 } ``` ## Inline metrics Every item carries the same rolled-up metrics the other monitor list endpoints return. They are computed per monitor over the calendar day, month and year in UTC. | Field | Type | Meaning | |------|-----|---------| | `uptimeDay` / `uptimeMonth` / `uptimeYear` | string | Uptime percentage with two decimals, e.g. `"99.94"` | | `avgResponseDay` / `avgResponseMonth` / `avgResponseYear` | number \| null | Average response time in milliseconds; `null` when nothing was measured in that window | | `responseGraph` | object | `{ values, avg }` for the last 24 hours, one entry per hour; an hour with no successful check is `null` | | `upSinceAt` | string \| null | ISO timestamp the monitor has been up since, `null` while it is down | | `isDown` | boolean | Whether the monitor is currently in an unresolved incident | The day figures are read from the raw check data, the month and year from continuous aggregates, so a value may lag the newest check by a few minutes in the month and year windows. ## Errors - `400` Invalid query parameters (e.g. `organizationId`, `customerId`) - `401` Unauthorized - `403` Forbidden ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `page` or `perPage` is not a positive integer, `sortOrder` is not `asc`/`desc`, or `tags` is not a comma-separated list of tag ids
### Trigger IMAP/POP Check
URL: https://docs.uptimeify.io/api/monitors/imap-pop-monitors/trigger-check-imap-pop-monitor
Description: Triggers an immediate check from all eligible monitoring locations.
Summary: `POST /api/imap-pop-monitors/:imapPopMonitorPublicId/trigger-check` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `imapPopMonitorPublicId` (Path, required): IMAP/POP monitor public UUID. ## Response ```json { "success": true, "message": "Checks triggered successfully", "imapPopMonitorId": 500, "locationCodes": ["de-nbg", "fi-hel"], "queueNames": ["imap-pop-monitor-checks-de-nbg", "imap-pop-monitor-checks-fi-hel"] } ``` ## Errors - `400` Invalid IMAP/POP monitor public ID (UUID) or no eligible locations - `401` Unauthorized - `403` Forbidden - `404` IMAP/POP monitor not found - `503` No active monitoring locations available - `500` Failed to trigger check
### Update IMAP/POP Monitor
URL: https://docs.uptimeify.io/api/monitors/imap-pop-monitors/update-imap-pop-monitor
Description: Updates an IMAP/POP monitor and/or changes its status.
Summary: `PATCH /api/imap-pop-monitors/:imapPopMonitorPublicId` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `imapPopMonitorPublicId` (Path, required): IMAP/POP monitor public UUID. ## Request Body - `status` (optional) - Allowed: `active`, `maintenance`, `disabled`, `paused`, `inactive` - Note: `paused` / `inactive` are normalized to `disabled`. - `name`, `hostname`, `port`, `checkInterval`, `timeoutSeconds` (optional) - `allowedCheckCountryCodes` (optional) - Normalized to upper-case and de-duplicated. - `checkMode` (optional) - Allowed: `protocol` | `tcp`. Must be one of these two values or the request fails with `400` / `data.code: "invalidCheckMode"`. - Switching to `tcp` clears any stored credentials: the monitor performs a bare TCP port-reachability check and `imapPopConfig` is not stored. Switching back to `protocol` re-enables the full IMAP/POP login check; supply `imapPopConfig`/`config` to set new credentials. - **`port` is required when the resulting `checkMode` is `tcp`** (either just set on this request, or already stored on the monitor). If no port is available, the request fails with `400` / `data.code: "portRequiredForTcp"`. - `imapPopConfig` (optional) - Alias for the stored `config` JSON. - `config` (optional) - Alternative way to update the same stored `config` JSON. Note: Read-only users may only change `status` (and sending any other fields will result in `403`). ```json { "status": "active" } ``` Example updating config: ```json { "imapPopConfig": { "protocol": "pop3", "tls": true, "user": "monitor@deinkunde.com", "password": "password" } } ``` ## Response ```json { "id": 500, "organizationId": 1, "customerId": 10, "name": "Mailbox Access", "hostname": "mail.deinkunde.com", "port": 993, "checkInterval": 30, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE"], "status": "active", "notificationPhoneNumber": null, "notificationEmail": null, "lastCheckedAt": null, "createdAt": "2026-02-26T12:00:00.000Z", "updatedAt": "2026-02-26T12:05:00.000Z", "config": { "protocol": "pop3", "tls": true, "user": "monitor@deinkunde.com", "password": "password" }, "imapPopConfig": { "protocol": "pop3", "tls": true, "user": "monitor@deinkunde.com", "password": "password" } } ``` ## Errors - `400` Invalid request body, invalid status, or invalid hostname - `401` Unauthorized - `403` Forbidden (e.g. `readonly` or global supporter) - `404` IMAP/POP monitor not found ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `name` is not a non-empty string of at most 255 characters, or `allowedCheckCountryCodes` is neither an array of country codes nor `null` - `400 Bad Request` (`invalidTimeoutSeconds`) if `timeoutSeconds` is not an integer between 1 and 60 - `400 Bad Request` (`invalidConfig`) if a config field (`config`, or the type-specific one) is not an object
### SMTP Monitors
URL: https://docs.uptimeify.io/api/monitors/smtp-monitors
Description: Manage SMTP monitors.
Summary: Path-based SMTP monitor endpoints use `smtpMonitorPublicId` UUIDs. ## Endpoints - [List SMTP Monitors](/api/monitors/smtp-monitors/list-smtp-monitors) - [Create SMTP Monitor](/api/monitors/smtp-monitors/create-smtp-monitor) - [Get SMTP Monitor](/api/monitors/smtp-monitors/get-smtp-monitor) - [Get SMTP Monitor Details](/api/monitors/smtp-monitors/get-smtp-monitor-details) - [Get SMTP Monitor Check History](/api/monitors/smtp-monitors/get-smtp-monitor-check-history) - [Update SMTP Monitor](/api/monitors/smtp-monitors/update-smtp-monitor) - [Delete SMTP Monitor](/api/monitors/smtp-monitors/delete-smtp-monitor) - [Trigger Check for SMTP Monitor](/api/monitors/smtp-monitors/trigger-check-smtp-monitor)
### Create SMTP Monitor
URL: https://docs.uptimeify.io/api/monitors/smtp-monitors/create-smtp-monitor
Description: Creates a new SMTP monitor.
Summary: `POST /api/smtp-monitors` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Request Body ```json { "customerId": "11111111-1111-4111-8111-111111111111", "name": "Outbound SMTP", "hostname": "smtp.deinkunde.com", "port": 587, "status": "active", "checkInterval": 60, "timeoutSeconds": 30, "smtpConfig": { "secure": false, "ignoreTls": false, "requireTls": false, "auth": { "user": "username", "pass": "password" } } } ``` ### Fields - `customerId` (number | string, required) - Accepts either the internal numeric customer ID or the public customer UUID. - `name` (string, required) - `hostname` (string, required) - Must be a hostname only (no protocol like `https://`, no path like `/smtp`). - `port` (number | null, optional) - If omitted or `null`, the worker defaults to `465` when `smtpConfig.secure=true`, otherwise `25`. - `status` (string, optional) - Allowed: `active`, `maintenance`, `disabled`, `paused`, `inactive` - `checkInterval` (number, optional) - `timeoutSeconds` (number, optional) - `checkMode` (string, optional) - Allowed: `protocol`, `tcp`. Defaults to `protocol`. - In `tcp` mode the monitor performs a bare TCP port-reachability check: `smtpConfig` is not required and is not stored. In `protocol` mode the full SMTP protocol/auth check runs (existing behavior). - `smtpConfig` (object, optional) - Stored as the monitor's `config` JSON. ### `smtpConfig` (worker-supported keys) The SMTP worker coerces/uses these keys: - `secure` (boolean, default `false`) - `ignoreTls` (boolean, default `false`) - `requireTls` (boolean, default `false`) - `auth.user` and `auth.pass` (strings) - Credentials are only used when *both* `user` and `pass` are provided. ### Duplicates If this customer already has a monitor with the same `hostname` (case and a trailing dot do not count), `port` and `checkMode`, the request is refused with `409` and `data.code` `monitorAlreadyExists`. `data.existingId` and `data.existingPublicId` name the existing monitor. Send `"allowDuplicate": true` to create the second monitor anyway (for example with a different interval or other alert channels). - `allowDuplicate` (boolean, optional, default `false`): create the monitor even if it is a duplicate. Not stored. ```json { "statusCode": 409, "statusMessage": "A monitor for this target already exists for this customer. Send allowDuplicate: true to create it anyway.", "data": { "code": "monitorAlreadyExists", "existingId": 300, "existingPublicId": "44444444-4444-4444-8444-444444444444" } } ``` ### Limit per target host An organization can have at most 100 monitors for the same target host, counted across all monitor types together (websites with HTTP, keyword, DNS website and Playwright with a real URL, plus TCP, ICMP, DNS, SSH, SMTP, FTP and IMAP/POP). The limit protects against the check fleet being misused as a load generator against third-party hosts. The exact hostname is compared: case, port, path and a trailing dot do not count, but `www.example.com` and `example.com` are different hosts. Once the limit is reached, the request is refused with `403` and `data.code` `targetHostMonitorLimitReached`. `data.host` names the normalized host, `data.limit` the limit. `"allowDuplicate": true` does not lift the limit. The same check runs when a PATCH changes the `hostname`. A PATCH that keeps the host always succeeds, and existing monitors above the limit stay in place. If you need a higher limit, contact support. Independently of your organization, at most 300 monitors across all Uptimeify customers may target the same host. Beyond that, the request is refused with `403` and `data.code` `targetHostPlatformLimitReached`; `data.host` and `data.limit` are set as above, and the message does not reveal how many monitors other organizations have. ```json { "statusCode": 403, "statusMessage": "Target host monitor limit reached: your organization already has 100 monitors for example.com (maximum 100 per host). Remove monitors for this hos…
### Delete SMTP Monitor
URL: https://docs.uptimeify.io/api/monitors/smtp-monitors/delete-smtp-monitor
Description: Deletes an SMTP monitor.
Summary: `DELETE /api/smtp-monitors/:smtpMonitorPublicId` ## Authentication Requires a valid session and write access. - Header: `Authorization: Bearer ` ## Parameters - `smtpMonitorPublicId` (Path, required): SMTP monitor public UUID. ## cURL ```bash curl -X DELETE "https://YOUR_DOMAIN/api/smtp-monitors/33333333-3333-4333-8333-333333333333" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "success": true } ``` ## Errors - `400` SMTP monitor public ID (UUID) required - `401` Unauthorized - `403` Forbidden (`readonlyMayNotDelete` for a read-only caller, `managed_by_organization` for a managed resource without `canEditManaged`) - `404` Not found ## Permissions Closed to the `readonly` role. A read-only login deletes no monitor, whatever its ownership class, and neither does an API token it issued: a token inherits the role of the user who created it. Editing a `self_service` monitor stays open to that role. A customer-scoped caller is bound by ownership class on top of that: a `managed` monitor is refused with `managed_by_organization` unless its customer carries `canEditManaged`.
### Get SMTP Monitor
URL: https://docs.uptimeify.io/api/monitors/smtp-monitors/get-smtp-monitor
Description: Returns details of a specific SMTP monitor.
Summary: `GET /api/smtp-monitors/:smtpMonitorPublicId` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `smtpMonitorPublicId` (Path, required): SMTP monitor public UUID. ## cURL ```bash curl "https://YOUR_DOMAIN/api/smtp-monitors/33333333-3333-4333-8333-333333333333" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "id": 200, "organizationId": 1, "customerId": 10, "name": "Outbound SMTP", "hostname": "smtp.deinkunde.com", "port": 587, "status": "active", "checkInterval": 60, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE"], "customerName": "Example Customer", "notificationEmail": null, "notificationPhoneNumber": null, "lastCheckedAt": "2026-01-01T12:00:00.000Z", "createdAt": "2026-01-01T12:00:00.000Z", "updatedAt": "2026-01-01T12:00:00.000Z", "config": { "secure": false, "ignoreTls": false, "requireTls": false }, "smtpConfig": { "secure": false, "ignoreTls": false, "requireTls": false } } ``` ## Errors - `400` SMTP monitor public ID (UUID) required - `401` Unauthorized - `404` Not found when the monitor does not exist **or belongs to another customer or organization** (the two cases are indistinguishable on purpose)
### Get SMTP Monitor Alert History
URL: https://docs.uptimeify.io/api/monitors/smtp-monitors/get-smtp-monitor-alert-history
Description: Returns notification/escalation attempts (alert history) for incidents of a SMTP monitor.
Summary: `GET /api/smtp-monitors/:smtpMonitorPublicId/alert-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `smtpMonitorPublicId` (Path, required): SMTP monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). - `limit` (number, optional): Items per page (default: `25`; max `100`). Ignored in favor of export defaults when `format=csv` or `download=1` (default `10000`, max `50000`). - `status` (string, optional): `sent` or `failed`. - `from` / `to` (ISO date string, optional): Filter by `sentAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` to force an attachment download, `0` (default) for the page. - `envelope` (string, optional): `items` answers as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/smtp-monitors/11111111-1111-4111-8111-111111111111/alert-history?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [ { "id": 987, "incidentId": 123, "type": "slack", "status": "sent", "channelName": "Ops Slack", "channelType": "slack", "channelConfig": null, "sentAt": "2026-02-26T12:11:00.000Z", "errorMessage": null } ], "total": 1, "page": 1, "perPage": 25 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }` (`perPage` is the `limit`). Without it the endpoint still answers the current form `{ data, total, page, pageCount }`, which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. Each entry is one delivery attempt to one notification channel. `status` is `sent` or `failed` (with `errorMessage` set on failure); `channelType` is the channel type (e.g. `email`, `slack`, `opsgenie`). `channelConfig` has secrets redacted. When `format=csv` (or `download=1`), the response is a `text/csv` (or `application/json` for `format=json&download=1`) attachment instead of the paginated JSON list above. ## Common Errors - `400 SMTP monitor public ID (UUID) required` if `:smtpMonitorPublicId` is invalid - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the monitor
### Get SMTP Monitor Check History
URL: https://docs.uptimeify.io/api/monitors/smtp-monitors/get-smtp-monitor-check-history
Description: Returns recent check results for an SMTP monitor.
Summary: `GET /api/smtp-monitors/:smtpMonitorPublicId/check-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `smtpMonitorPublicId` (Path, required): SMTP monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). A page counts check cycles, not rows: one cycle has one row per location. - `limit` (number, optional): Cycles per page (default: `10`; max `100`). With `format=csv` or `download=1` the export defaults apply instead (default `10000`, max `50000` rows). - `status` (string, optional): `success` or `failure` (`failure` also matches `timeout`). On minute rows: no failed location, or at least one. - `minMs` / `maxMs` (number, optional): Filter by response time range (`timingTotal`; on minute rows the minute average). - `from` / `to` (ISO date string, optional): Filter by `checkedAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` forces an attachment download. ## cURL ```bash curl "https://YOUR_DOMAIN/api/smtp-monitors/44444444-4444-4444-8444-444444444444/check-history?page=1&limit=10" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "data": [ { "id": "33c53ac4-a2bc-475c-a904-8d3d6aab2979", "status": "success", "success": true, "errorMessage": null, "checkedAt": "2026-10-01T05:40:55.690Z", "responseTimeMs": 29, "location": { "name": "Paris (FR)", "code": "par" }, "resolution": "raw" }, { "id": "1min-2026-09-30T15:55:00.000Z", "status": "success", "success": true, "errorMessage": null, "checkedAt": "2026-09-30T15:55:00.000Z", "responseTimeMs": 54, "location": null, "resolution": "1min", "totalLocations": 2, "failedLocations": 0 } ], "total": 864, "page": 17, "pageCount": 87, "resolution": "mixed", "rawWindowFrom": "2026-09-30T16:00:00.000Z" } ``` - `resolution` per row: `raw` is a single check with location and error message; `1min` is one minute across all locations, without location or error message, with `totalLocations` and `failedLocations`. - `resolution` of the page: `raw`, `1min` or `mixed` (the page spans the boundary). - `rawWindowFrom`: where individual checks begin; older rows are minute rows. With `format=csv` (or `download=1`) the response is a `text/csv` attachment (or `application/json` for `format=json&download=1`) instead of the paginated JSON above. CSV columns: `checkedAt,status,responseTimeMs,location,errorMessage,resolution`. ## Data retention Individual checks, with location and error message, are kept for 24 hours. Older entries come from minute aggregates (30 days), one row per minute without location or error message. Daily figures (24 months) are available through the monitor details. ## Errors - `400` SMTP monitor public ID (UUID) required - `401` Unauthorized - `403` Forbidden - `404` Not found ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status`, `minMs` or `maxMs` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date
### Get SMTP Monitor Details
URL: https://docs.uptimeify.io/api/monitors/smtp-monitors/get-smtp-monitor-details
Description: Consolidated endpoint that returns the SMTP monitor details page data in one call.
Summary: `GET /api/smtp-monitors/:smtpMonitorPublicId/details` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `smtpMonitorPublicId` (Path, required): SMTP monitor public UUID. ## Query Parameters - `range` (string, optional): `day`, `week`, `month`, `year` (default: `day`) - `date` (string, optional): Reference date (parsed by `new Date(date)`) - `startDate` (string, optional) - `endDate` (string, optional) - `granularity` (string, optional) - `raw` disables aggregation, `aggregated` forces it. Default: raw up to 48 hours. ## cURL ```bash curl "https://YOUR_DOMAIN/api/smtp-monitors/33333333-3333-4333-8333-333333333333/details?range=day" \ -H "Authorization: Bearer $TOKEN" ``` ## Response The response is a single object with these top-level keys: - `smtpMonitorId` - `monitor` - `latestCheck` - `uptimeStats` - `uptimeStatsMeta` - `monitoringData` - `incidents` - `alerts` - `testResultLog` - `maintenance` Example (truncated): ```json { "smtpMonitorId": 200, "monitor": { "id": 200, "customerId": 10, "name": "Outbound SMTP", "hostname": "smtp.deinkunde.com", "port": 587, "status": "active", "checkInterval": 60, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE"], "config": { "secure": false, "requireTls": true } }, "latestCheck": { "status": "success", "checkedAt": "2026-01-01T12:00:00.000Z", "timingSmtp": 123, "locationCode": "de-nbg", "locationName": "Nuremberg (DE)" }, "uptimeStats": { "day": 99.9, "month": 99.5, "year": 99.0, "dayAvgResponse": 120, "monthAvgResponse": 140, "yearAvgResponse": 150 }, "maintenance": { "inMaintenance": false, "activeWindows": [], "allWindows": [] } } ``` ## Data retention Single checks are kept for 24 hours, minute aggregates for 30 days and daily aggregates for 24 months; a range older than 30 days returns one point per day. If the monitor has no check within the last 24 hours, `latestCheck` describes its last minute from the aggregate: `id` starts with `1min-`, `resolution` is `1min`, and `locationId` and `errorMessage` are `null`. ## Errors - `400` Invalid SMTP monitor public ID (UUID) - `401` Unauthorized - `403` Forbidden - `404` Not found - `500` Failed to fetch SMTP monitor details ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `range` is not `day`/`week`/`month`/`year`, `date`/`startDate`/`endDate` is not a date, only one of `startDate`/`endDate` is given, `tz` is not an integer, or `granularity` is not `raw`/`aggregated`
### Get SMTP Monitor Incident History
URL: https://docs.uptimeify.io/api/monitors/smtp-monitors/get-smtp-monitor-incident-history
Description: Returns incidents for a single SMTP monitor (latest 100), including a computed duration.
Summary: `GET /api/smtp-monitors/:smtpMonitorPublicId/incident-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `smtpMonitorPublicId` (Path, required): SMTP monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). - `limit` (number, optional): Items per page (default: `25`; max `100`). Ignored in favor of export defaults when `format=csv` or `download=1` (default `10000`, max `50000`). - `status` (string, optional): `open`, `acknowledged`, or `resolved`. - `type` (string, optional): `downtime`, `http_status`, `ssl_expiry`, `ssl_critical`, `ssl_warning`, `response_time`, `dnsbl`, `domain_expiry_warning`, `critical`, or `inconclusive`. - `from` / `to` (ISO date string, optional): Filter by `startedAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` to force an attachment download, `0` (default) for the page. - `envelope` (string, optional): `items` answers as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/smtp-monitors/11111111-1111-4111-8111-111111111111/incident-history?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [ { "id": 123, "publicId": "55555555-5555-4555-8555-555555555555", "type": "downtime", "status": "resolved", "startedAt": "2026-02-26T12:10:00.000Z", "endedAt": "2026-02-26T12:12:30.000Z", "durationMs": 150000, "statusCode": null, "errorMessage": "connect ETIMEDOUT", "details": "connect ETIMEDOUT", "isOngoing": false } ], "total": 1, "page": 1, "perPage": 25 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }` (`perPage` is the `limit`). Without it the endpoint still answers the current form `{ data, total, page, pageCount }`, which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. **Deprecated field:** `duration` (text, e.g. `2m 30s`) is still sent next to `durationMs` until it is removed on 2027-01-18. Read `durationMs`. `status` is `open`, `acknowledged`, or `resolved`. Ongoing incidents have a `null` `endedAt` and `isOngoing: true`. When `format=csv` (or `download=1`), the response is a `text/csv` (or `application/json` for `format=json&download=1`) attachment instead of the paginated JSON list above. ## Common Errors - `400 SMTP monitor public ID (UUID) required` if `:smtpMonitorPublicId` is invalid - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status` or `type` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the monitor
### List SMTP Monitors
URL: https://docs.uptimeify.io/api/monitors/smtp-monitors/list-smtp-monitors
Description: Lists SMTP monitors in an organization.
Summary: `GET /api/smtp-monitors` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `organizationId` (Query, optional): Organization ID. Defaults to the current user's organization. - `customerId` (Query, optional): Filter by customer ID. - `search` (Query, optional): Search by monitor name, hostname, or customer. - `page` (Query, optional): Page number (default: 1). - `perPage` (Query, optional): Items per page (default: 50, max: 200). ## cURL ```bash curl "https://YOUR_DOMAIN/api/smtp-monitors?page=1&perPage=50" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "items": [ { "id": 200, "organizationId": 1, "customerId": 10, "name": "Outbound SMTP", "hostname": "smtp.deinkunde.com", "port": 587, "status": "active", "checkInterval": 60, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE"], "customerName": "Example Customer", "notificationEmail": null, "notificationPhoneNumber": null, "lastCheckedAt": "2026-01-01T12:00:00.000Z", "createdAt": "2026-01-01T12:00:00.000Z", "updatedAt": "2026-01-01T12:00:00.000Z", "config": { "secure": false, "ignoreTls": false, "requireTls": false } } ], "total": 1, "page": 1, "perPage": 50 } ``` ## Inline metrics Every item carries the same rolled-up metrics the other monitor list endpoints return. They are computed per monitor over the calendar day, month and year in UTC. | Field | Type | Meaning | |------|-----|---------| | `uptimeDay` / `uptimeMonth` / `uptimeYear` | string | Uptime percentage with two decimals, e.g. `"99.94"` | | `avgResponseDay` / `avgResponseMonth` / `avgResponseYear` | number \| null | Average response time in milliseconds; `null` when nothing was measured in that window | | `responseGraph` | object | `{ values, avg }` for the last 24 hours, one entry per hour; an hour with no successful check is `null` | | `upSinceAt` | string \| null | ISO timestamp the monitor has been up since, `null` while it is down | | `isDown` | boolean | Whether the monitor is currently in an unresolved incident | The day figures are read from the raw check data, the month and year from continuous aggregates, so a value may lag the newest check by a few minutes in the month and year windows. ## Errors - `400` Invalid `organizationId` or `customerId` - `401` Unauthorized - `403` Forbidden ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `page` or `perPage` is not a positive integer, `sortOrder` is not `asc`/`desc`, or `tags` is not a comma-separated list of tag ids
### Trigger Check for SMTP Monitor
URL: https://docs.uptimeify.io/api/monitors/smtp-monitors/trigger-check-smtp-monitor
Description: Triggers an immediate check from all eligible monitoring locations.
Summary: `POST /api/smtp-monitors/:smtpMonitorPublicId/trigger-check` ## Authentication Requires a valid session and write access. - Header: `Authorization: Bearer ` ## Parameters - `smtpMonitorPublicId` (Path, required): SMTP monitor public UUID. ## cURL ```bash curl -X POST "https://YOUR_DOMAIN/api/smtp-monitors/33333333-3333-4333-8333-333333333333/trigger-check" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "success": true, "message": "Checks triggered successfully", "smtpMonitorId": 200, "locationCodes": ["de-nbg", "fi-hel"], "queueNames": ["smtp-monitor-checks-de-nbg", "smtp-monitor-checks-fi-hel"] } ``` ## Errors - `400` SMTP monitor public ID (UUID) required - `401` Unauthorized - `403` Forbidden - `404` Not found - `500` Failed to trigger check (the status message may include e.g. "No active monitoring locations available")
### Update SMTP Monitor
URL: https://docs.uptimeify.io/api/monitors/smtp-monitors/update-smtp-monitor
Description: Updates an SMTP monitor.
Summary: `PATCH /api/smtp-monitors/:smtpMonitorPublicId` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `smtpMonitorPublicId` (Path, required): SMTP monitor public UUID. ## Request Body All fields are optional. ```json { "name": "Outbound SMTP (Primary)", "hostname": "smtp.deinkunde.com", "port": 587, "status": "paused", "checkInterval": 60, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["de", "es"], "smtpConfig": { "secure": false, "requireTls": true, "auth": { "user": "username", "pass": "password" } } } ``` ### Notes - `status` accepts `active`, `maintenance`, `disabled`, `paused`, `inactive`. - `paused` and `inactive` are normalized to `disabled`. - `allowedCheckCountryCodes` is normalized to uppercase ISO codes (e.g. `DE`, `US`). Empty lists become `null`. - `checkMode` (string, optional): `protocol` (default) | `tcp`. Switching to `tcp` clears any stored credentials: the monitor performs a bare TCP port-reachability check and `smtpConfig` is not stored. Switching back to `protocol` re-enables the full SMTP protocol/auth check; supply `smtpConfig`/`config` to set new credentials. - SMTP config can be provided as `smtpConfig` or as `config` (alias). If neither is provided, the stored config is not changed. - Users with `readonly` role can only change `status`. ## cURL ```bash curl -X PATCH "https://YOUR_DOMAIN/api/smtp-monitors/33333333-3333-4333-8333-333333333333" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "disabled" }' ``` ## Response ```json { "id": 200, "organizationId": 1, "customerId": 10, "name": "Outbound SMTP (Primary)", "hostname": "smtp.deinkunde.com", "port": 587, "status": "disabled", "checkInterval": 60, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE"], "notificationEmail": null, "notificationPhoneNumber": null, "lastCheckedAt": "2026-01-01T12:00:00.000Z", "createdAt": "2026-01-01T12:00:00.000Z", "updatedAt": "2026-01-01T12:01:00.000Z", "config": { "secure": false, "requireTls": true, "auth": { "user": "username", "pass": "password" } }, "smtpConfig": { "secure": false, "requireTls": true, "auth": { "user": "username", "pass": "password" } } } ``` ## Errors - `400` SMTP monitor public ID (UUID) required - `401` Unauthorized - `403` Forbidden (readonly users may only update `status`; global supporters cannot update) - `404` Not found ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `name` is not a non-empty string of at most 255 characters, or `allowedCheckCountryCodes` is neither an array of country codes nor `null` - `400 Bad Request` (`invalidTimeoutSeconds`) if `timeoutSeconds` is not an integer between 1 and 60 - `400 Bad Request` (`invalidConfig`) if a config field (`config`, or the type-specific one) is not an object
### SSH Monitors
URL: https://docs.uptimeify.io/api/monitors/ssh-monitors
Description: Manage SSH monitors.
Summary: Path-based SSH monitor endpoints use `sshMonitorPublicId` UUIDs. ## Endpoints - [List SSH Monitors](/api/monitors/ssh-monitors/list-ssh-monitors) - [Create SSH Monitor](/api/monitors/ssh-monitors/create-ssh-monitor) - [Get SSH Monitor](/api/monitors/ssh-monitors/get-ssh-monitor) - [Get SSH Monitor Details](/api/monitors/ssh-monitors/get-ssh-monitor-details) - [Get SSH Monitor Check History](/api/monitors/ssh-monitors/get-ssh-monitor-check-history) - [Update SSH Monitor](/api/monitors/ssh-monitors/update-ssh-monitor) - [Delete SSH Monitor](/api/monitors/ssh-monitors/delete-ssh-monitor) - [Trigger Check for SSH Monitor](/api/monitors/ssh-monitors/trigger-check-ssh-monitor)
### Create SSH Monitor
URL: https://docs.uptimeify.io/api/monitors/ssh-monitors/create-ssh-monitor
Description: Creates a new SSH monitor.
Summary: `POST /api/ssh-monitors` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Request Body ```json { "customerId": "11111111-1111-4111-8111-111111111111", "name": "Bastion Host", "hostname": "ssh.deinkunde.com", "port": 22, "status": "active", "checkInterval": 60, "timeoutSeconds": 30, "sshConfig": { "username": "root", "password": "password", "privateKey": "-----BEGIN OPENSSH PRIVATE KEY-----..." } } ``` ### Fields - `customerId` (number | string, required) - Accepts either the internal numeric customer ID or the public customer UUID. - `name` (string, required) - `hostname` (string, required) - Must be a hostname only (no protocol like `https://`, no path like `/ssh`). - `port` (number | null, optional) - If omitted or `null`, the worker defaults to port `22`. - `status` (string, optional) - Allowed: `active`, `maintenance`, `disabled`, `paused`, `inactive` - `checkInterval` (number, optional) - `timeoutSeconds` (number, optional) - `checkMode` (string, optional) - Allowed: `protocol`, `tcp`. Defaults to `protocol`. - In `tcp` mode the monitor performs a bare TCP port-reachability check: `sshConfig` is not required and is not stored. In `protocol` mode the full SSH login/handshake check runs (existing behavior). - `sshConfig` (object, optional) - Stored as the monitor's `config` JSON. - Required (username + password or privateKey) unless `checkMode` is `tcp`. ### `sshConfig` (worker-supported keys) - `username` (string) - If omitted, the worker uses `anonymous`. - `password` (string) - `privateKey` (string) ### Duplicates If this customer already has a monitor with the same `hostname` (case and a trailing dot do not count), `port` and `checkMode`, the request is refused with `409` and `data.code` `monitorAlreadyExists`. `data.existingId` and `data.existingPublicId` name the existing monitor. Send `"allowDuplicate": true` to create the second monitor anyway (for example with a different interval or other alert channels). - `allowDuplicate` (boolean, optional, default `false`): create the monitor even if it is a duplicate. Not stored. ```json { "statusCode": 409, "statusMessage": "A monitor for this target already exists for this customer. Send allowDuplicate: true to create it anyway.", "data": { "code": "monitorAlreadyExists", "existingId": 300, "existingPublicId": "44444444-4444-4444-8444-444444444444" } } ``` ### Limit per target host An organization can have at most 100 monitors for the same target host, counted across all monitor types together (websites with HTTP, keyword, DNS website and Playwright with a real URL, plus TCP, ICMP, DNS, SSH, SMTP, FTP and IMAP/POP). The limit protects against the check fleet being misused as a load generator against third-party hosts. The exact hostname is compared: case, port, path and a trailing dot do not count, but `www.example.com` and `example.com` are different hosts. Once the limit is reached, the request is refused with `403` and `data.code` `targetHostMonitorLimitReached`. `data.host` names the normalized host, `data.limit` the limit. `"allowDuplicate": true` does not lift the limit. The same check runs when a PATCH changes the `hostname`. A PATCH that keeps the host always succeeds, and existing monitors above the limit stay in place. If you need a higher limit, contact support. Independently of your organization, at most 300 monitors across all Uptimeify customers may target the same host. Beyond that, the request is refused with `403` and `data.code` `targetHostPlatformLimitReached`; `data.host` and `data.limit` are set as above, and the message does not reveal how many monitors other organizations have. ```json { "statusCode": 403, "statusMessage": "Target host monitor limit reached: your organization already has 100 monitors for example.com (maximum 100 per host). Remove monitors for this host or contact support to raise the limit.", "data": { "code": "targetHostMonitorLimitReached", "host": "example.com", "limit": 100 } } ``` ## cURL `…
### Delete SSH Monitor
URL: https://docs.uptimeify.io/api/monitors/ssh-monitors/delete-ssh-monitor
Description: Deletes an SSH monitor.
Summary: `DELETE /api/ssh-monitors/:sshMonitorPublicId` ## Authentication Requires a valid session and write access. - Header: `Authorization: Bearer ` ## Parameters - `sshMonitorPublicId` (Path, required): SSH monitor public UUID. ## cURL ```bash curl -X DELETE "https://YOUR_DOMAIN/api/ssh-monitors/44444444-4444-4444-8444-444444444444" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "success": true } ``` ## Errors - `400` SSH monitor public ID (UUID) required - `401` Unauthorized - `403` Forbidden (`readonlyMayNotDelete` for a read-only caller, `managed_by_organization` for a managed resource without `canEditManaged`) - `404` Not found ## Permissions Closed to the `readonly` role. A read-only login deletes no monitor, whatever its ownership class, and neither does an API token it issued: a token inherits the role of the user who created it. Editing a `self_service` monitor stays open to that role. A customer-scoped caller is bound by ownership class on top of that: a `managed` monitor is refused with `managed_by_organization` unless its customer carries `canEditManaged`.
### Get SSH Monitor
URL: https://docs.uptimeify.io/api/monitors/ssh-monitors/get-ssh-monitor
Description: Returns details of a specific SSH monitor.
Summary: `GET /api/ssh-monitors/:sshMonitorPublicId` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `sshMonitorPublicId` (Path, required): SSH monitor public UUID. ## cURL ```bash curl "https://YOUR_DOMAIN/api/ssh-monitors/44444444-4444-4444-8444-444444444444" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "id": 300, "organizationId": 1, "customerId": 10, "name": "Bastion Host", "hostname": "ssh.deinkunde.com", "port": 22, "status": "active", "checkInterval": 60, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE"], "customerName": "Example Customer", "notificationEmail": null, "notificationPhoneNumber": null, "lastCheckedAt": "2026-02-26T12:00:00.000Z", "createdAt": "2026-02-26T12:00:00.000Z", "updatedAt": "2026-02-26T12:00:00.000Z", "config": { "username": "root" }, "sshConfig": { "username": "root" } } ``` ## Errors - `400` SSH monitor public ID (UUID) required - `401` Unauthorized - `404` Not found when the monitor does not exist **or belongs to another customer or organization** (the two cases are indistinguishable on purpose)
### Get SSH Monitor Alert History
URL: https://docs.uptimeify.io/api/monitors/ssh-monitors/get-ssh-monitor-alert-history
Description: Returns notification/escalation attempts (alert history) for incidents of a SSH monitor.
Summary: `GET /api/ssh-monitors/:sshMonitorPublicId/alert-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `sshMonitorPublicId` (Path, required): SSH monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). - `limit` (number, optional): Items per page (default: `25`; max `100`). Ignored in favor of export defaults when `format=csv` or `download=1` (default `10000`, max `50000`). - `status` (string, optional): `sent` or `failed`. - `from` / `to` (ISO date string, optional): Filter by `sentAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` to force an attachment download, `0` (default) for the page. - `envelope` (string, optional): `items` answers as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/ssh-monitors/11111111-1111-4111-8111-111111111111/alert-history?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [ { "id": 987, "incidentId": 123, "type": "slack", "status": "sent", "channelName": "Ops Slack", "channelType": "slack", "channelConfig": null, "sentAt": "2026-02-26T12:11:00.000Z", "errorMessage": null } ], "total": 1, "page": 1, "perPage": 25 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }` (`perPage` is the `limit`). Without it the endpoint still answers the current form `{ data, total, page, pageCount }`, which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. Each entry is one delivery attempt to one notification channel. `status` is `sent` or `failed` (with `errorMessage` set on failure); `channelType` is the channel type (e.g. `email`, `slack`, `opsgenie`). `channelConfig` has secrets redacted. When `format=csv` (or `download=1`), the response is a `text/csv` (or `application/json` for `format=json&download=1`) attachment instead of the paginated JSON list above. ## Common Errors - `400 SSH monitor public ID (UUID) required` if `:sshMonitorPublicId` is invalid - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the monitor
### Get SSH Monitor Check History
URL: https://docs.uptimeify.io/api/monitors/ssh-monitors/get-ssh-monitor-check-history
Description: Returns recent check results for an SSH monitor.
Summary: `GET /api/ssh-monitors/:sshMonitorPublicId/check-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `sshMonitorPublicId` (Path, required): SSH monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). A page counts check cycles, not rows: one cycle has one row per location. - `limit` (number, optional): Cycles per page (default: `10`; max `100`). With `format=csv` or `download=1` the export defaults apply instead (default `10000`, max `50000` rows). - `status` (string, optional): `success` or `failure` (`failure` also matches `timeout`). On minute rows: no failed location, or at least one. - `minMs` / `maxMs` (number, optional): Filter by response time range (`timingTotal`; on minute rows the minute average). - `from` / `to` (ISO date string, optional): Filter by `checkedAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` forces an attachment download. ## cURL ```bash curl "https://YOUR_DOMAIN/api/ssh-monitors/44444444-4444-4444-8444-444444444444/check-history?page=1&limit=10" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "data": [ { "id": "33c53ac4-a2bc-475c-a904-8d3d6aab2979", "status": "success", "success": true, "errorMessage": null, "checkedAt": "2026-10-01T05:40:55.690Z", "responseTimeMs": 29, "location": { "name": "Paris (FR)", "code": "par" }, "resolution": "raw" }, { "id": "1min-2026-09-30T15:55:00.000Z", "status": "success", "success": true, "errorMessage": null, "checkedAt": "2026-09-30T15:55:00.000Z", "responseTimeMs": 54, "location": null, "resolution": "1min", "totalLocations": 2, "failedLocations": 0 } ], "total": 864, "page": 17, "pageCount": 87, "resolution": "mixed", "rawWindowFrom": "2026-09-30T16:00:00.000Z" } ``` - `resolution` per row: `raw` is a single check with location and error message; `1min` is one minute across all locations, without location or error message, with `totalLocations` and `failedLocations`. - `resolution` of the page: `raw`, `1min` or `mixed` (the page spans the boundary). - `rawWindowFrom`: where individual checks begin; older rows are minute rows. With `format=csv` (or `download=1`) the response is a `text/csv` attachment (or `application/json` for `format=json&download=1`) instead of the paginated JSON above. CSV columns: `checkedAt,status,responseTimeMs,location,errorMessage,resolution`. ## Data retention Individual checks, with location and error message, are kept for 24 hours. Older entries come from minute aggregates (30 days), one row per minute without location or error message. Daily figures (24 months) are available through the monitor details. ## Errors - `400` SSH monitor public ID (UUID) required - `401` Unauthorized - `403` Forbidden - `404` Not found ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status`, `minMs` or `maxMs` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date
### Get SSH Monitor Details
URL: https://docs.uptimeify.io/api/monitors/ssh-monitors/get-ssh-monitor-details
Description: Consolidated endpoint that returns the SSH monitor details page data in one call.
Summary: `GET /api/ssh-monitors/:sshMonitorPublicId/details` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `sshMonitorPublicId` (Path, required): SSH monitor public UUID. ## Query Parameters - `range` (string, optional): `day`, `week`, `month`, `year` (default: `day`) - `date` (string, optional): Reference date (parsed by `new Date(date)`) - `startDate` (string, optional) - `endDate` (string, optional) - `granularity` (string, optional) - `raw` disables aggregation, `aggregated` forces it. Default: raw up to 48 hours. ## cURL ```bash curl "https://YOUR_DOMAIN/api/ssh-monitors/44444444-4444-4444-8444-444444444444/details?range=day" \ -H "Authorization: Bearer $TOKEN" ``` ## Response The response is a single object with these top-level keys: - `sshMonitorId` - `monitor` - `latestCheck` - `uptimeStats` - `uptimeStatsMeta` - `monitoringData` - `incidents` - `alerts` - `testResultLog` - `maintenance` Example (truncated): ```json { "sshMonitorId": 300, "monitor": { "id": 300, "customerId": 10, "name": "Bastion Host", "hostname": "ssh.deinkunde.com", "port": 22, "status": "active", "checkInterval": 60, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE"], "config": { "username": "root" } }, "latestCheck": { "status": "success", "checkedAt": "2026-02-26T12:00:00.000Z", "timingSsh": 123, "locationCode": "de-nbg", "locationName": "Nuremberg (DE)" }, "uptimeStats": { "day": 99.9, "month": 99.5, "year": 99.0, "dayAvgResponse": 120, "monthAvgResponse": 140, "yearAvgResponse": 150 }, "maintenance": { "inMaintenance": false, "activeWindows": [], "allWindows": [] } } ``` ## Data retention Single checks are kept for 24 hours, minute aggregates for 30 days and daily aggregates for 24 months; a range older than 30 days returns one point per day. If the monitor has no check within the last 24 hours, `latestCheck` describes its last minute from the aggregate: `id` starts with `1min-`, `resolution` is `1min`, and `locationId` and `errorMessage` are `null`. ## Errors - `400` Invalid SSH monitor public ID (UUID) - `401` Unauthorized - `403` Forbidden - `404` Not found - `500` Failed to fetch SSH monitor details ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `range` is not `day`/`week`/`month`/`year`, `date`/`startDate`/`endDate` is not a date, only one of `startDate`/`endDate` is given, `tz` is not an integer, or `granularity` is not `raw`/`aggregated`
### Get SSH Monitor Incident History
URL: https://docs.uptimeify.io/api/monitors/ssh-monitors/get-ssh-monitor-incident-history
Description: Returns incidents for a single SSH monitor (latest 100), including a computed duration.
Summary: `GET /api/ssh-monitors/:sshMonitorPublicId/incident-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `sshMonitorPublicId` (Path, required): SSH monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). - `limit` (number, optional): Items per page (default: `25`; max `100`). Ignored in favor of export defaults when `format=csv` or `download=1` (default `10000`, max `50000`). - `status` (string, optional): `open`, `acknowledged`, or `resolved`. - `type` (string, optional): `downtime`, `http_status`, `ssl_expiry`, `ssl_critical`, `ssl_warning`, `response_time`, `dnsbl`, `domain_expiry_warning`, `critical`, or `inconclusive`. - `from` / `to` (ISO date string, optional): Filter by `startedAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` to force an attachment download, `0` (default) for the page. - `envelope` (string, optional): `items` answers as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/ssh-monitors/11111111-1111-4111-8111-111111111111/incident-history?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [ { "id": 123, "publicId": "55555555-5555-4555-8555-555555555555", "type": "downtime", "status": "resolved", "startedAt": "2026-02-26T12:10:00.000Z", "endedAt": "2026-02-26T12:12:30.000Z", "durationMs": 150000, "statusCode": null, "errorMessage": "connect ETIMEDOUT", "details": "connect ETIMEDOUT", "isOngoing": false } ], "total": 1, "page": 1, "perPage": 25 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }` (`perPage` is the `limit`). Without it the endpoint still answers the current form `{ data, total, page, pageCount }`, which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. **Deprecated field:** `duration` (text, e.g. `2m 30s`) is still sent next to `durationMs` until it is removed on 2027-01-18. Read `durationMs`. `status` is `open`, `acknowledged`, or `resolved`. Ongoing incidents have a `null` `endedAt` and `isOngoing: true`. When `format=csv` (or `download=1`), the response is a `text/csv` (or `application/json` for `format=json&download=1`) attachment instead of the paginated JSON list above. ## Common Errors - `400 SSH monitor public ID (UUID) required` if `:sshMonitorPublicId` is invalid - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status` or `type` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the monitor
### List SSH Monitors
URL: https://docs.uptimeify.io/api/monitors/ssh-monitors/list-ssh-monitors
Description: Lists SSH monitors in an organization.
Summary: `GET /api/ssh-monitors` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `organizationId` (Query, optional): Organization ID. Defaults to the current user's organization. - `customerId` (Query, optional): Filter by customer ID. - `search` (Query, optional): Search by monitor name, hostname, or customer. - `page` (Query, optional): Page number (default: 1). - `perPage` (Query, optional): Items per page (default: 50, max: 200). ## cURL ```bash curl "https://YOUR_DOMAIN/api/ssh-monitors?page=1&perPage=50" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "items": [ { "id": 300, "organizationId": 1, "customerId": 10, "name": "Bastion Host", "hostname": "ssh.deinkunde.com", "port": 22, "status": "active", "checkInterval": 60, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE"], "customerName": "Example Customer", "notificationEmail": null, "notificationPhoneNumber": null, "lastCheckedAt": "2026-02-26T12:00:00.000Z", "createdAt": "2026-02-26T12:00:00.000Z", "updatedAt": "2026-02-26T12:00:00.000Z", "config": { "username": "root" } } ], "total": 1, "page": 1, "perPage": 50 } ``` ## Inline metrics Every item carries the same rolled-up metrics the other monitor list endpoints return. They are computed per monitor over the calendar day, month and year in UTC. | Field | Type | Meaning | |------|-----|---------| | `uptimeDay` / `uptimeMonth` / `uptimeYear` | string | Uptime percentage with two decimals, e.g. `"99.94"` | | `avgResponseDay` / `avgResponseMonth` / `avgResponseYear` | number \| null | Average response time in milliseconds; `null` when nothing was measured in that window | | `responseGraph` | object | `{ values, avg }` for the last 24 hours, one entry per hour; an hour with no successful check is `null` | | `upSinceAt` | string \| null | ISO timestamp the monitor has been up since, `null` while it is down | | `isDown` | boolean | Whether the monitor is currently in an unresolved incident | The day figures are read from the raw check data, the month and year from continuous aggregates, so a value may lag the newest check by a few minutes in the month and year windows. ## Errors - `400` Invalid `organizationId` or `customerId` - `401` Unauthorized - `403` Forbidden ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `page` or `perPage` is not a positive integer, `sortOrder` is not `asc`/`desc`, or `tags` is not a comma-separated list of tag ids
### Trigger Check for SSH Monitor
URL: https://docs.uptimeify.io/api/monitors/ssh-monitors/trigger-check-ssh-monitor
Description: Triggers an immediate check from all eligible monitoring locations.
Summary: `POST /api/ssh-monitors/:sshMonitorPublicId/trigger-check` ## Authentication Requires a valid session and write access. - Header: `Authorization: Bearer ` ## Parameters - `sshMonitorPublicId` (Path, required): SSH monitor public UUID. ## cURL ```bash curl -X POST "https://YOUR_DOMAIN/api/ssh-monitors/44444444-4444-4444-8444-444444444444/trigger-check" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "success": true, "message": "Checks triggered successfully", "sshMonitorId": 300, "locationCodes": ["de-nbg", "fi-hel"], "queueNames": ["ssh-monitor-checks-de-nbg", "ssh-monitor-checks-fi-hel"] } ``` ## Errors - `400` SSH monitor public ID (UUID) required - `401` Unauthorized - `403` Forbidden - `404` Not found - `500` Failed to trigger check (the status message may include e.g. "No active monitoring locations available")
### Update SSH Monitor
URL: https://docs.uptimeify.io/api/monitors/ssh-monitors/update-ssh-monitor
Description: Updates an SSH monitor.
Summary: `PATCH /api/ssh-monitors/:sshMonitorPublicId` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `sshMonitorPublicId` (Path, required): SSH monitor public UUID. ## Request Body All fields are optional. ```json { "name": "Bastion Host (Primary)", "hostname": "ssh.deinkunde.com", "port": 22, "status": "paused", "checkInterval": 60, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["de", "es"], "sshConfig": { "username": "root", "privateKey": "-----BEGIN OPENSSH PRIVATE KEY-----..." } } ``` ### Notes - `status` accepts `active`, `maintenance`, `disabled`, `paused`, `inactive`. - `paused` and `inactive` are normalized to `disabled`. - `allowedCheckCountryCodes` is normalized to uppercase ISO codes (e.g. `DE`, `US`). Empty lists become `null`. - `checkMode` (string, optional): `protocol` (default) | `tcp`. Switching to `tcp` clears any stored credentials: the monitor performs a bare TCP port-reachability check and `sshConfig` is not stored. Switching back to `protocol` re-enables the full SSH login/handshake check; supply `sshConfig`/`config` to set new credentials. - SSH config can be provided as `sshConfig` or as `config` (alias). If neither is provided, the stored config is not changed. - Users with `readonly` role can only change `status`. ## cURL ```bash curl -X PATCH "https://YOUR_DOMAIN/api/ssh-monitors/44444444-4444-4444-8444-444444444444" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "disabled" }' ``` ## Response ```json { "id": 300, "organizationId": 1, "customerId": 10, "name": "Bastion Host (Primary)", "hostname": "ssh.deinkunde.com", "port": 22, "status": "disabled", "checkInterval": 60, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE"], "notificationEmail": null, "notificationPhoneNumber": null, "lastCheckedAt": "2026-02-26T12:00:00.000Z", "createdAt": "2026-02-26T12:00:00.000Z", "updatedAt": "2026-02-26T12:01:00.000Z", "config": { "username": "root" }, "sshConfig": { "username": "root" } } ``` ## Errors - `400` SSH monitor ID is required / invalid fields - `401` Unauthorized - `403` Forbidden (readonly users may only update `status`; global supporters cannot update) - `404` Not found ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `name` is not a non-empty string of at most 255 characters, or `allowedCheckCountryCodes` is neither an array of country codes nor `null` - `400 Bad Request` (`invalidTimeoutSeconds`) if `timeoutSeconds` is not an integer between 1 and 60 - `400 Bad Request` (`invalidConfig`) if a config field (`config`, or the type-specific one) is not an object
### TCP Monitors
URL: https://docs.uptimeify.io/api/monitors/tcp-monitors
Description: Manage TCP monitors.
Summary: Path-based TCP monitor endpoints use `tcpMonitorPublicId` UUIDs. ## Endpoints - [List TCP Monitors](/api/monitors/tcp-monitors/list-tcp-monitors) - [Create TCP Monitor](/api/monitors/tcp-monitors/create-tcp-monitor) - [Get TCP Monitor](/api/monitors/tcp-monitors/get-tcp-monitor) - [Get TCP Monitor Details](/api/monitors/tcp-monitors/get-tcp-monitor-details) - [Get TCP Monitor Check History](/api/monitors/tcp-monitors/get-tcp-monitor-check-history) - [Get TCP Monitor Alert History](/api/monitors/tcp-monitors/get-tcp-monitor-alert-history) - [Get TCP Monitor Incident History](/api/monitors/tcp-monitors/get-tcp-monitor-incident-history) - [Update TCP Monitor](/api/monitors/tcp-monitors/update-tcp-monitor) - [Delete TCP Monitor](/api/monitors/tcp-monitors/delete-tcp-monitor) - [Trigger Check for TCP Monitor](/api/monitors/tcp-monitors/trigger-check-tcp-monitor)
### Create TCP Monitor
URL: https://docs.uptimeify.io/api/monitors/tcp-monitors/create-tcp-monitor
Description: Creates a new TCP monitor.
Summary: `POST /api/tcp-monitors` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Request Body ```json { "customerId": "11111111-1111-4111-8111-111111111111", "name": "Redis Primary", "hostname": "redis.deinkunde.com", "port": 6379, "status": "active", "checkInterval": 60, "timeoutSeconds": 30, "config": { "expectBanner": "+PONG" } } ``` ### Fields - `customerId` (number | string, required) - Accepts either the internal numeric customer ID or the public customer UUID. - `name` (string, required, max 255 chars) - `hostname` (string, required, max 253 chars) - Must be a hostname only (no protocol like `https://`, no path like `/status`). - `port` (number, **required**, 1-65535) - Unlike other monitor types, TCP monitors have no default port. You must specify the port to connect to. - `status` (string, optional) - Allowed: `active`, `maintenance`, `disabled`, `paused`, `inactive` (`paused`/`inactive` are normalized to `disabled`). Defaults to `active`. - `checkInterval` (number, optional, 1-1440 minutes) - Defaults to `30`. - `timeoutSeconds` (number, optional, 1-60) - Defaults to `30`. - `allowedCheckCountryCodes` (string[], optional) - Restricts checks to these ISO-3166-1 alpha-2 country codes. - `managementType` (string, optional) - Allowed: `managed`, `self_service`. Only organization writers may set this; other callers always get `managed`. - `config` (object, optional) - Stored as the monitor's `config` JSON. TCP monitors carry **no credentials**: the only supported key is `expectBanner`. - `expectedState` (string, optional, top level, not inside `config`) - `up` (default): alert when the port is not reachable. `down`: alert when the port accepts a connection, for ports that must stay closed (e.g. a maintenance or debug port). Connection refused, timeout, reset and host or network unreachable count as closed (healthy); DNS resolution errors and other errors still fail, so a typo in the hostname does not look green. `expectBanner` is ignored while `expectedState` is `down`. ### `config` (worker-supported keys) - `expectBanner` (string, optional, max 255 chars) - If set, the worker verifies that the raw bytes received right after the TCP handshake contain this substring (e.g. `+PONG` for Redis, `220` for an SMTP banner). If omitted, the check only verifies that the TCP handshake succeeds. ### Duplicates If this customer already has a monitor with the same `hostname` (case and a trailing dot do not count) and `port`, the request is refused with `409` and `data.code` `monitorAlreadyExists`. `data.existingId` and `data.existingPublicId` name the existing monitor. Send `"allowDuplicate": true` to create the second monitor anyway (for example with a different interval or other alert channels). - `allowDuplicate` (boolean, optional, default `false`): create the monitor even if it is a duplicate. Not stored. ```json { "statusCode": 409, "statusMessage": "A monitor for this target already exists for this customer. Send allowDuplicate: true to create it anyway.", "data": { "code": "monitorAlreadyExists", "existingId": 300, "existingPublicId": "44444444-4444-4444-8444-444444444444" } } ``` ### Limit per target host An organization can have at most 100 monitors for the same target host, counted across all monitor types together (websites with HTTP, keyword, DNS website and Playwright with a real URL, plus TCP, ICMP, DNS, SSH, SMTP, FTP and IMAP/POP). The limit protects against the check fleet being misused as a load generator against third-party hosts. The exact hostname is compared: case, port, path and a trailing dot do not count, but `www.example.com` and `example.com` are different hosts. Once the limit is reached, the request is refused with `403` and `data.code` `targetHostMonitorLimitReached`. `data.host` names the normalized host, `data.limit` the limit. `"allowDuplicate": true` does not lift the limit. The same check runs when a PATCH changes the `hostname`. A PATCH that keeps the host always suc…
### Delete TCP Monitor
URL: https://docs.uptimeify.io/api/monitors/tcp-monitors/delete-tcp-monitor
Description: Deletes a TCP monitor.
Summary: `DELETE /api/tcp-monitors/:tcpMonitorPublicId` ## Authentication Requires a valid session and write access. - Header: `Authorization: Bearer ` ## Parameters - `tcpMonitorPublicId` (Path, required): TCP monitor public UUID. ## cURL ```bash curl -X DELETE "https://YOUR_DOMAIN/api/tcp-monitors/44444444-4444-4444-8444-444444444444" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "success": true } ``` ## Errors - `400` TCP monitor public ID (UUID) required - `401` Unauthorized - `403` Forbidden (`readonlyMayNotDelete` for a read-only caller, `managed_by_organization` for a managed resource without `canEditManaged`) - `404` Not found ## Permissions Closed to the `readonly` role. A read-only login deletes no monitor, whatever its ownership class, and neither does an API token it issued: a token inherits the role of the user who created it. Editing a `self_service` monitor stays open to that role. A customer-scoped caller is bound by ownership class on top of that: a `managed` monitor is refused with `managed_by_organization` unless its customer carries `canEditManaged`.
### Get TCP Monitor
URL: https://docs.uptimeify.io/api/monitors/tcp-monitors/get-tcp-monitor
Description: Returns details of a specific TCP monitor.
Summary: `GET /api/tcp-monitors/:tcpMonitorPublicId` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `tcpMonitorPublicId` (Path, required): TCP monitor public UUID. ## cURL ```bash curl "https://YOUR_DOMAIN/api/tcp-monitors/44444444-4444-4444-8444-444444444444" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "id": 300, "publicId": "44444444-4444-4444-8444-444444444444", "organizationId": 1, "customerId": 10, "name": "Redis Primary", "hostname": "redis.deinkunde.com", "port": 6379, "status": "active", "managementType": "managed", "checkInterval": 60, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE"], "customerName": "Example Customer", "notificationEmail": null, "notificationPhoneNumber": null, "lastCheckedAt": "2026-02-26T12:00:00.000Z", "createdAt": "2026-02-26T12:00:00.000Z", "updatedAt": "2026-02-26T12:00:00.000Z", "expectedState": "up", "config": { "expectBanner": "+PONG" } } ``` ## Errors - `400` TCP monitor public ID (UUID) required - `401` Unauthorized - `404` Not found when the monitor does not exist **or belongs to another customer or organization** (the two cases are indistinguishable on purpose)
### Get TCP Monitor Alert History
URL: https://docs.uptimeify.io/api/monitors/tcp-monitors/get-tcp-monitor-alert-history
Description: Returns paginated notification/escalation attempts (alert history) for incidents of a TCP monitor.
Summary: `GET /api/tcp-monitors/:tcpMonitorPublicId/alert-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `tcpMonitorPublicId` (Path, required): TCP monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). - `limit` (number, optional): Items per page (default: `25`; max `100`). Ignored in favor of export defaults when `format=csv` or `download=1` (default `10000`, max `50000`). - `status` (string, optional): `sent` or `failed`. - `from` / `to` (ISO date string, optional): Filter by `sentAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` to force an attachment download, `0` (default) for the page. - `envelope` (string, optional): `items` answers as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/tcp-monitors/11111111-1111-4111-8111-111111111111/alert-history?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [ { "id": 987, "incidentId": 123, "type": "slack", "status": "sent", "channelName": "Ops Slack", "channelType": "slack", "channelConfig": null, "sentAt": "2026-02-26T12:11:00.000Z", "errorMessage": null } ], "total": 1, "page": 1, "perPage": 25 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }` (`perPage` is the `limit`). Without it the endpoint still answers the current form `{ data, total, page, pageCount }`, which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. Each entry is one delivery attempt to one notification channel. `status` is `sent` or `failed` (with `errorMessage` set on failure); `channelType` is the channel type (e.g. `email`, `slack`, `opsgenie`). `channelConfig` has secrets redacted. When `format=csv` (or `download=1`), the response is a `text/csv` (or `application/json` for `format=json&download=1`) attachment instead of the paginated JSON list above. ## Common Errors - `400 TCP monitor public ID (UUID) required` if `:tcpMonitorPublicId` is invalid - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the monitor
### Get TCP Monitor Check History
URL: https://docs.uptimeify.io/api/monitors/tcp-monitors/get-tcp-monitor-check-history
Description: Returns paginated check results for a TCP monitor.
Summary: `GET /api/tcp-monitors/:tcpMonitorPublicId/check-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `tcpMonitorPublicId` (Path, required): TCP monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). A page counts check cycles, not rows: one cycle has one row per location. - `limit` (number, optional): Cycles per page (default: `10`; max `100`). With `format=csv` or `download=1` the export defaults apply instead (default `10000`, max `50000` rows). - `status` (string, optional): `success` or `failure` (`failure` also matches `timeout`). On minute rows: no failed location, or at least one. - `minMs` / `maxMs` (number, optional): Filter by response time range (`timingTotal`; on minute rows the minute average). - `from` / `to` (ISO date string, optional): Filter by `checkedAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` forces an attachment download. ## cURL ```bash curl "https://YOUR_DOMAIN/api/tcp-monitors/44444444-4444-4444-8444-444444444444/check-history?page=1&limit=10" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "data": [ { "id": "33c53ac4-a2bc-475c-a904-8d3d6aab2979", "status": "success", "success": true, "errorMessage": null, "checkedAt": "2026-10-01T05:40:55.690Z", "responseTimeMs": 29, "location": { "name": "Paris (FR)", "code": "par" }, "resolution": "raw" }, { "id": "1min-2026-09-30T15:55:00.000Z", "status": "success", "success": true, "errorMessage": null, "checkedAt": "2026-09-30T15:55:00.000Z", "responseTimeMs": 54, "location": null, "resolution": "1min", "totalLocations": 2, "failedLocations": 0 } ], "total": 864, "page": 17, "pageCount": 87, "resolution": "mixed", "rawWindowFrom": "2026-09-30T16:00:00.000Z" } ``` - `resolution` per row: `raw` is a single check with location and error message; `1min` is one minute across all locations, without location or error message, with `totalLocations` and `failedLocations`. - `resolution` of the page: `raw`, `1min` or `mixed` (the page spans the boundary). - `rawWindowFrom`: where individual checks begin; older rows are minute rows. With `format=csv` (or `download=1`) the response is a `text/csv` attachment (or `application/json` for `format=json&download=1`) instead of the paginated JSON above. CSV columns: `checkedAt,status,responseTimeMs,location,errorMessage,resolution`. ## Data retention Individual checks, with location and error message, are kept for 24 hours. Older entries come from minute aggregates (30 days), one row per minute without location or error message. Daily figures (24 months) are available through the monitor details. ## Errors - `400` TCP monitor public ID (UUID) required - `401` Unauthorized - `403` Forbidden - `404` Not found ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status`, `minMs` or `maxMs` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date
### Get TCP Monitor Details
URL: https://docs.uptimeify.io/api/monitors/tcp-monitors/get-tcp-monitor-details
Description: Consolidated endpoint that returns the TCP monitor details page data in one call.
Summary: `GET /api/tcp-monitors/:tcpMonitorPublicId/details` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `tcpMonitorPublicId` (Path, required): TCP monitor public UUID. ## Query Parameters - `range` (string, optional): `day`, `week`, `month`, `year` (default: `day`) - `date` (string, optional): Reference date (parsed by `new Date(date)`) - `startDate` (string, optional) - `endDate` (string, optional) - `granularity` (string, optional) - `raw` disables aggregation, `aggregated` forces it. Default: raw up to 48 hours. ## cURL ```bash curl "https://YOUR_DOMAIN/api/tcp-monitors/44444444-4444-4444-8444-444444444444/details?range=day" \ -H "Authorization: Bearer $TOKEN" ``` ## Response The response is a single object with these top-level keys: - `tcpMonitorId` - `monitor` - `latestCheck` - `uptimeStats` - `uptimeStatsMeta` - `monitoringData` - `incidents` - `alerts` - `testResultLog` - `maintenance` Example (truncated): ```json { "tcpMonitorId": 300, "monitor": { "id": 300, "customerId": 10, "name": "Redis Primary", "hostname": "redis.deinkunde.com", "port": 6379, "status": "active", "checkInterval": 60, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE"], "config": { "expectBanner": "+PONG" } }, "latestCheck": { "status": "success", "checkedAt": "2026-02-26T12:00:00.000Z", "timingTotal": 123, "locationCode": "de-nbg", "locationName": "Nuremberg (DE)" }, "uptimeStats": { "day": 99.9, "month": 99.5, "year": 99.0, "dayAvgResponse": 120, "monthAvgResponse": 140, "yearAvgResponse": 150 }, "maintenance": { "inMaintenance": false, "activeWindows": [], "allWindows": [] } } ``` ## Data retention Single checks are kept for 24 hours, minute aggregates for 30 days and daily aggregates for 24 months; a range older than 30 days returns one point per day. If the monitor has no check within the last 24 hours, `latestCheck` describes its last minute from the aggregate: `id` starts with `1min-`, `resolution` is `1min`, and `locationId` and `errorMessage` are `null`. ## Errors - `400` Invalid TCP monitor public ID (UUID) - `401` Unauthorized - `403` Forbidden - `404` Not found - `500` Failed to fetch TCP monitor details ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `range` is not `day`/`week`/`month`/`year`, `date`/`startDate`/`endDate` is not a date, only one of `startDate`/`endDate` is given, `tz` is not an integer, or `granularity` is not `raw`/`aggregated`
### Get TCP Monitor Incident History
URL: https://docs.uptimeify.io/api/monitors/tcp-monitors/get-tcp-monitor-incident-history
Description: Returns paginated incidents for a single TCP monitor, including a computed duration.
Summary: `GET /api/tcp-monitors/:tcpMonitorPublicId/incident-history` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `tcpMonitorPublicId` (Path, required): TCP monitor public UUID. ## Query Parameters - `page` (number, optional): Page number (default: `1`). - `limit` (number, optional): Items per page (default: `25`; max `100`). Ignored in favor of export defaults when `format=csv` or `download=1` (default `10000`, max `50000`). - `status` (string, optional): `open`, `acknowledged`, or `resolved`. - `type` (string, optional): `downtime`, `http_status`, `ssl_expiry`, `ssl_critical`, `ssl_warning`, `response_time`, `dnsbl`, `domain_expiry_warning`, `critical`, or `inconclusive`. - `from` / `to` (ISO date string, optional): Filter by `startedAt` range. - `format` (string, optional): `json` (default) or `csv`. - `download` (string, optional): `1` to force an attachment download, `0` (default) for the page. - `envelope` (string, optional): `items` answers as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/tcp-monitors/11111111-1111-4111-8111-111111111111/incident-history?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Example Response ```json { "items": [ { "id": 123, "publicId": "55555555-5555-4555-8555-555555555555", "type": "downtime", "status": "resolved", "startedAt": "2026-02-26T12:10:00.000Z", "endedAt": "2026-02-26T12:12:30.000Z", "durationMs": 150000, "statusCode": null, "errorMessage": "connect ETIMEDOUT", "details": "connect ETIMEDOUT", "isOngoing": false } ], "total": 1, "page": 1, "perPage": 25 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }` (`perPage` is the `limit`). Without it the endpoint still answers the current form `{ data, total, page, pageCount }`, which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. **Deprecated field:** `duration` (text, e.g. `2m 30s`) is still sent next to `durationMs` until it is removed on 2027-01-18. Read `durationMs`. `status` is `open`, `acknowledged`, or `resolved`. Ongoing incidents have a `null` `endedAt` and `isOngoing: true`. When `format=csv` (or `download=1`), the response is a `text/csv` (or `application/json` for `format=json&download=1`) attachment instead of the paginated JSON list above. ## Common Errors - `400 TCP monitor public ID (UUID) required` if `:tcpMonitorPublicId` is invalid - `400 Bad Request` (`invalidRequestBody`) if a query parameter is invalid: `page`/`limit` not a positive integer, `format` not `json`/`csv`, `download` not `0`/`1`, or an unknown value in `status` or `type` - `400 Bad Request` (`invalidDateRange`) if `from` or `to` is not a date - `401 Unauthorized` if you are not authenticated - `403 Forbidden` if you do not have access to the monitor
### List TCP Monitors
URL: https://docs.uptimeify.io/api/monitors/tcp-monitors/list-tcp-monitors
Description: Lists TCP monitors in an organization.
Summary: `GET /api/tcp-monitors` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `organizationId` (Query, optional): Organization ID. Defaults to the current user's organization. - `customerId` (Query, optional): Filter by customer ID. - `search` (Query, optional): Search by monitor name, hostname, or customer. - `page` (Query, optional): Page number (default: 1). - `perPage` (Query, optional): Items per page (default: 50, max: 200). ## cURL ```bash curl "https://YOUR_DOMAIN/api/tcp-monitors?page=1&perPage=50" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "items": [ { "id": 300, "publicId": "44444444-4444-4444-8444-444444444444", "organizationId": 1, "customerId": 10, "name": "Redis Primary", "hostname": "redis.deinkunde.com", "port": 6379, "status": "active", "managementType": "managed", "checkInterval": 60, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE"], "customerName": "Example Customer", "notificationEmail": null, "notificationPhoneNumber": null, "lastCheckedAt": "2026-02-26T12:00:00.000Z", "createdAt": "2026-02-26T12:00:00.000Z", "updatedAt": "2026-02-26T12:00:00.000Z", "expectedState": "up", "config": { "expectBanner": "+PONG" }, "tags": [] } ], "total": 1, "page": 1, "perPage": 50 } ``` ## Inline metrics Every item carries the same rolled-up metrics the other monitor list endpoints return. They are computed per monitor over the calendar day, month and year in UTC. | Field | Type | Meaning | |------|-----|---------| | `uptimeDay` / `uptimeMonth` / `uptimeYear` | string | Uptime percentage with two decimals, e.g. `"99.94"` | | `avgResponseDay` / `avgResponseMonth` / `avgResponseYear` | number \| null | Average response time in milliseconds; `null` when nothing was measured in that window | | `responseGraph` | object | `{ values, avg }` for the last 24 hours, one entry per hour; an hour with no successful check is `null` | | `upSinceAt` | string \| null | ISO timestamp the monitor has been up since, `null` while it is down | | `isDown` | boolean | Whether the monitor is currently in an unresolved incident | The day figures are read from the raw check data, the month and year from continuous aggregates, so a value may lag the newest check by a few minutes in the month and year windows. ## Errors - `400` Invalid `organizationId` or `customerId` - `401` Unauthorized - `403` Forbidden ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `page` or `perPage` is not a positive integer, `sortOrder` is not `asc`/`desc`, or `tags` is not a comma-separated list of tag ids
### Trigger Check for TCP Monitor
URL: https://docs.uptimeify.io/api/monitors/tcp-monitors/trigger-check-tcp-monitor
Description: Triggers an immediate check from one eligible monitoring location.
Summary: `POST /api/tcp-monitors/:tcpMonitorPublicId/trigger-check` ## Authentication Requires a valid session and write access. - Header: `Authorization: Bearer ` ## Parameters - `tcpMonitorPublicId` (Path, required): TCP monitor public UUID. ## Notes - The location is chosen deterministically from the currently active monitoring locations (filtered by the monitor's or customer's `allowedCheckCountryCodes`, if set). - Rate-limited per monitor via a short cooldown; retrying too soon returns `429`. ## cURL ```bash curl -X POST "https://YOUR_DOMAIN/api/tcp-monitors/44444444-4444-4444-8444-444444444444/trigger-check" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "success": true, "message": "Check triggered successfully", "tcpMonitorId": 300, "locationCode": "de-nbg", "queueName": "tcp-monitor-checks-de-nbg" } ``` ## Errors - `400` No eligible monitoring locations for the selected allowed countries - `401` Unauthorized - `403` Forbidden - `404` Not found - `429` Check recently triggered: retry after the cooldown (`retryAfterMs` on the error payload) - `500` / `503` Failed to trigger check (e.g. "No active monitoring locations available")
### Update TCP Monitor
URL: https://docs.uptimeify.io/api/monitors/tcp-monitors/update-tcp-monitor
Description: Updates a TCP monitor.
Summary: `PATCH /api/tcp-monitors/:tcpMonitorPublicId` ## Authentication Requires a valid session. - Header: `Authorization: Bearer ` ## Parameters - `tcpMonitorPublicId` (Path, required): TCP monitor public UUID. ## Request Body All fields are optional. ```json { "name": "Redis Primary", "hostname": "redis.deinkunde.com", "port": 6379, "status": "paused", "checkInterval": 60, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["de", "es"], "config": { "expectBanner": "+PONG" } } ``` ### Notes - `status` accepts `active`, `maintenance`, `disabled`, `paused`, `inactive`. - `paused` and `inactive` are normalized to `disabled`. - `port`, if provided, must be an integer between `1` and `65535`. - `allowedCheckCountryCodes` is normalized to uppercase ISO codes (e.g. `DE`, `US`). Empty lists become `null`. - `config` only accepts the `expectBanner` key (merged into the existing stored config). There is no `sshConfig`-style alias and no credential fields. TCP monitors carry no credentials. If omitted, the stored config is not changed. - `expectedState` (`up` or `down`, top level, not inside `config`) switches between alerting when the port is not reachable (`up`) and alerting when it accepts a connection (`down`); see Create TCP Monitor for what counts as closed. `expectBanner` is ignored while it is `down`. If omitted, the stored value is not changed. - Users with `readonly` role can only change `status`. ## cURL ```bash curl -X PATCH "https://YOUR_DOMAIN/api/tcp-monitors/44444444-4444-4444-8444-444444444444" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "disabled" }' ``` ## Response ```json { "id": 300, "publicId": "44444444-4444-4444-8444-444444444444", "organizationId": 1, "customerId": 10, "name": "Redis Primary", "hostname": "redis.deinkunde.com", "port": 6379, "status": "disabled", "managementType": "managed", "checkInterval": 60, "timeoutSeconds": 30, "allowedCheckCountryCodes": ["DE"], "notificationEmail": null, "notificationPhoneNumber": null, "lastCheckedAt": "2026-02-26T12:00:00.000Z", "createdAt": "2026-02-26T12:00:00.000Z", "updatedAt": "2026-02-26T12:01:00.000Z", "expectedState": "up", "config": { "expectBanner": "+PONG" } } ``` ## Errors - `400` TCP monitor ID is required / invalid fields (e.g. `invalidPort`, `invalidConfig`, `invalidStatus`) - `401` Unauthorized - `403` Forbidden (readonly users may only update `status`; global supporters cannot update) - `404` Not found ## Common Errors - `400 Bad Request` (`invalidRequestBody`) if `name` is not a non-empty string of at most 255 characters, or `allowedCheckCountryCodes` is neither an array of country codes nor `null` - `400 Bad Request` (`invalidTimeoutSeconds`) if `timeoutSeconds` is not an integer between 1 and 60 - `400 Bad Request` (`invalidConfig`) if a config field (`config`, or the type-specific one) is not an object
### Notification Channels
URL: https://docs.uptimeify.io/api/notification-channels
Description: Manage how and where alerts are delivered. Channels can be organization-level (default for all customers), customer-level (override for a specific customer), or website-level (override for a specific monitor).
Summary: ## Authentication All examples assume a bearer token: ```bash BASE_URL="https://uptimeify.io" TOKEN="" ``` ## Channel Types and Config Each channel type has a specific `config` structure: | Type | Config Fields | Notes | |------|--------------|-------| | `email` | `{ email, to }` | Email address and recipient name | | `sms` | `{ phoneNumber }` | Phone number in international format | | `webhook` | `{ url, method?, headers?, bodyTemplate?, timeout?, retryAttempts?, retryDelay?, expectedStatusCodes?, secret? }` | HTTP webhook. `secret` for HMAC signing | | `slack` | `{ webhookUrl, username?, iconEmoji?, color? }` | Slack incoming webhook URL. The URL embeds the posting token and is treated as a secret | | `discord` | `{ webhookUrl, username?, color? }` | Discord incoming webhook URL. The URL embeds the posting token and is treated as a secret | | `teams` | `{ webhookUrl }` | Microsoft Teams workflow / connector URL. Treated as a secret | | `pagerduty` | `{ routingKey }` | PagerDuty Events API v2 routing key | | `pushover` | `{ userKey, apiToken }` | Pushover user key and API token | | `opsgenie` | `{ apiKey }` | Opsgenie API key | Secrets (webhook `secret`, Slack/Discord/Teams webhook URLs, PagerDuty routing keys, Pushover credentials, Opsgenie API keys) are **encrypted at rest** and **redacted in API responses**: the value comes back as `null`, and a boolean flag next to it says whether one is stored (`hasSecret`, `hasWebhookUrl`, `hasRoutingKey`, …). A Slack, Discord or Teams channel therefore reads as `"config": { "webhookUrl": null, "hasWebhookUrl": true, … }`. On `PATCH`, leaving such a field out (or sending `null` / an empty string) keeps the stored value; sending a new value replaces it. The generic `webhook` type is the exception: its `url` is the customer's own address and stays visible, only its `secret` is redacted. ## Webhook Signature Verification When a `secret` is configured on a webhook channel, Uptimeify signs outgoing payloads so receivers can verify authenticity. **Algorithm:** HMAC-SHA256 **Header:** `X-Webhook-Signature`: hex-encoded HMAC-SHA256 digest **Companion headers sent with every webhook:** | Header | Value | |--------|-------| | `X-Webhook-Signature` | Hex-encoded HMAC-SHA256 digest | | `X-Webhook-Signature-Algorithm` | `sha256` | | `X-Webhook-Timestamp` | ISO 8601 timestamp (e.g. `2026-05-05T12:00:00.000Z`) | | `X-Webhook-Attempt` | 1-based retry number (e.g. `1`, `2`, `3`) | | `X-Webhook-Event` | Event type: `alert`, `recovery`, or `dnsbl` | **Verification steps:** 1. Read the raw request body as a string (do not parse as JSON first). 2. Compute HMAC-SHA256 using the `secret` you configured in the channel as the key and the raw body string as the message. 3. Compare the result (hex-encoded) with the value of the `X-Webhook-Signature` header using a constant-time comparison. 4. Optionally check `X-Webhook-Timestamp` for replay protection. ```javascript // Node.js verification example const crypto = require('crypto') function verifySignature(rawBody, signature, secret) { const expected = crypto .createHmac('sha256', secret) .update(rawBody) .digest('hex') return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expected) ) } ``` ```python # Python verification example def verify_signature(raw_body, signature, secret): expected = hmac.new( secret.encode('utf-8'), raw_body.encode('utf-8'), hashlib.sha256 ).hexdigest() return hmac.compare_digest(signature, expected) ``` ## Scope Resolution When listing channels, the scope determines which channels are returned: - **Organization-level** (`organizationId` only, no `customerId`/`websiteId`): Default channels for all customers - **Customer-level** (`customerId` set, no `websiteId`): Customer-specific overrides - **Website-level** (`websiteId` set): Per-monitor overrides ## Endpoints - [List Notification Channels](/api/notification-channels/list-notification-channels) - [Get Notification Channel](/api/notification-channels/get-noti…
### Create Notification Channel
URL: https://docs.uptimeify.io/api/notification-channels/create-notification-channel
Description: Creates a new notification channel. Secrets in config are encrypted server-side.
Summary: `POST /api/notification-channels` ## Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `type` | string | Yes | - | Channel type, one of the list below (anything else is a `400`) | | `name` | string | Yes | - | Display name, 1 to 100 characters | | `config` | object\|string | Yes | - | Channel configuration (see type table). Pass as JSON object or JSON string of at most 20 kB. | | `organizationId` | number | No | from session | Organization scope | | `customerId` | number | No | null | Customer scope | | `websiteId` | number | No | null | Website scope. Requires `sourceChannelId`. | | `sourceChannelId` | number\|string | Conditional | null | Parent channel ID for website overrides | | `category` | string | No | `direct` | `direct` or `integration` | | `delaySeconds` | number | No | 0 | Delay before sending alert, integer 0 to 86400 | | `conditions` | object\|string | No | null | Alert conditions (e.g., `{"onlyFullService": true, "minIncidentDuration": 300}`), JSON object or JSON string of at most 20 kB | | `isActive` | boolean | No | true | Whether the channel is active | `delaySeconds` runs on its own timer for this channel, starting from the moment this channel would notify, independent of any other channel on the same alert. If a maintenance window starts before that time elapses, or the incident is already resolved by then, nothing is delivered on this channel. `priority` has been removed from channel configuration. A request that still sends it is accepted and the field is simply ignored, so existing integrations keep working unchanged. ## Channel types Direct (`category: "direct"`): `email`, `sms`, `webhook`. Integrations (`category: "integration"`): `incident_management`, `slack`, `discord`, `teams`, `pagerduty`, `opsgenie`, `allquiet`, `telegram`, `googlechat`, `mattermost`, `rocketchat`, `matrix`, `lark`, `dingtalk`, `wecom`, `ilert`, `grafanaoncall`, `squadcast`, `incidentio`, `pushover`, `ntfy`, `gotify`, `jira`, `github`, `gitlab`, `linear`, `servicenow`. The `config` fields depend on the type: see [Integrations](/integrations) for what each channel needs. You can validate a channel before saving with the [Test Notification Channel](/api/notification-channels/test-notification-channel) endpoint. ### `incident_management` Uptimeify's own Incident Management is an integration channel like any other, with two differences: - It takes an **empty `config`** (`{}`). There is no endpoint and no credential, confirmed outages are delivered internally. - It is **not testable**: the [Test Notification Channel](/api/notification-channels/test-notification-channel) endpoint does not support this type. What the channel controls is *which* monitors page through Incident Management. Its scope (`customerId` / `websiteId`, both optional, omit both for the whole organization) and its `allowedPackageTypes` decide whose confirmed outages become IM incidents; everything else stays on classic notifications. A monitoring outage only reaches Incident Management when a matching, active channel exists **and** the customer's package has integration alerts enabled. ## Example (cURL): Email channel ```bash curl -X POST "$BASE_URL/api/notification-channels" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "email", "name": "Ops Email", "config": { "email": "ops@deinkunde.com", "to": "Ops Team " }, "organizationId": 1 }' ``` ## Example (cURL): Slack channel ```bash curl -X POST "$BASE_URL/api/notification-channels" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "slack", "name": "Alerts Slack Channel", "config": { "webhookUrl": "https://hooks.slack.com/services/T00/B00/xxx" }, "organizationId": 1 }' ``` ## Example (cURL): Webhook channel ```bash curl -X POST "$BASE_URL/api/notification-channels" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type…
### Delete Notification Channel
URL: https://docs.uptimeify.io/api/notification-channels/delete-notification-channel
Description: Deletes a notification channel. If the channel was an org-level default, organization defaults are automatically synced.
Summary: `DELETE /api/notification-channels/:id` ## Example (cURL) ```bash curl -X DELETE "$BASE_URL/api/notification-channels/1" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "success": true } ``` ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` when accessing channels outside your scope - `404 Not found` when the channel does not exist ## Permissions Organization admins may write channels at any level. A customer-scoped login (role `readonly`) may create, update and delete channels bound to one of ITS OWN customers: that is what the integrations page in the dashboard offers the role, and until 04.09.2026 the API refused it with a bare `403`. Two limits remain. An ORGANIZATION-level channel, one carrying no `customerId`, stays admin-only. And a channel of a customer outside the caller's scope is refused, as before. The roles `editor` and `responder` are not writers here.
### Get Notification Channel
URL: https://docs.uptimeify.io/api/notification-channels/get-notification-channel
Description: Returns one notification channel, in the same shape as an entry of List Notification Channels. Secrets in config are redacted.
Summary: `GET /api/notification-channels/{id}` ## Access The same scope check as editing the channel, read-only: a website channel needs read access to that website, a customer channel needs that customer in your scope (a customer-scoped API token only reaches its own customer), an organization channel needs read access to the organization. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/notification-channels/42" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response `200 OK` ```json { "id": 42, "organizationId": 10, "customerId": 5, "websiteId": null, "type": "webhook", "category": "alert", "name": "Ops webhook", "config": { "webhookUrl": "https://hooks.example.com/t/1", "secret": "********" }, "delaySeconds": 0, "conditions": null, "allowedPackageTypes": null, "isActive": true, "verifiedAt": null, "createdAt": "2026-06-01T08:00:00.000Z" } ``` ## Common errors - `400 Bad Request` (`invalidChannelId`) when the id is not a positive number - `401 Unauthorized` when you are not logged in - `403 Forbidden` when the channel is outside your scope - `404 Not Found` (`channelNotFound`) when the channel does not exist
### List Notification Channels
URL: https://docs.uptimeify.io/api/notification-channels/list-notification-channels
Description: Returns notification channels scoped by organization, customer, or website.
Summary: `GET /api/notification-channels` ## Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `organizationId` | number | No | Scope to organization | | `customerId` | number | No | Scope to customer | | `websiteId` | number | No | Scope to website (includes org + customer channels) | | `envelope` | string | No | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ## Example (cURL) ```bash curl -X GET "$BASE_URL/api/notification-channels?organizationId=1&envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "items": [ { "id": 1, "organizationId": 1, "customerId": null, "websiteId": null, "type": "email", "category": "direct", "name": "Ops Email", "config": { "email": "ops@deinkunde.com", "to": "Ops Team" }, "delaySeconds": 0, "conditions": null, "isActive": true, "allowedPackageTypes": null }, { "id": 2, "organizationId": 1, "customerId": null, "websiteId": null, "type": "slack", "category": "integration", "name": "Alerts Slack Channel", "config": { "webhookUrl": null, "hasWebhookUrl": true, "username": "Uptimeify" }, "delaySeconds": 0, "conditions": null, "isActive": true, "allowedPackageTypes": null } ], "total": 2, "page": 1, "perPage": 2 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form (a bare array of the same items), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. Secrets inside `config` are never returned: a Slack, Discord or Teams webhook URL comes back as `null` with `hasWebhookUrl: true` next to it, see "Channel Types and Config" on the Notification Channels overview page. Custom HTTP headers (`config.headers`, `config.webhookHeaders`) keep their names but never return their values: `{ "X-Api-Key": null }`, with `hasHeaders: true` in `config`. Values are stored encrypted. Until 20.10.2026 the values came back in plain text. ## Visibility Without `websiteId` and without `customerId`, which channels come back depends on who is reading: - An **unrestricted reader** (organization admin, global admin, and an organization-bound agent token) receives the organization-level channels, that is those with `customerId: null` and `websiteId: null`. - A **customer-scoped reader** (a `readonly` user or an `editor` with explicit customer assignments, plus the API or agent token minted for such a user) receives the channels of their own customers in addition to the organization-level ones. Channels of another customer are never returned. Naming `customerId` returns that customer's channels plus the organization-level ones. Naming `websiteId` additionally returns the website's own override channels. ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` when accessing channels outside your scope
### Test Notification Channel
URL: https://docs.uptimeify.io/api/notification-channels/test-notification-channel
Description: Tests a notification channel configuration. Optionally sends a real test message.
Summary: `POST /api/notification-channels/test` ## Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `type` | string | Yes | - | `webhook`, `slack`, `discord`, `pagerduty`, `pushover`, `opsgenie` | | `config` | object | Yes | `{}` | Channel config with secrets | | `organizationId` | number | No | from session | Organization scope | | `customerId` | number | No | null | Customer scope | | `websiteId` | number | No | null | Website scope | | `channelId` | number | No | - | Existing channel being tested. A header in `config` with value `null` or `""` then uses that channel's stored value (needs edit access to the channel). Without it such a header is left out. | | `dryRun` | boolean | No | false | If true, validates only (no actual send) | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/notification-channels/test" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "webhook", "config": { "url": "https://deinkunde.com/webhook", "method": "POST", "timeout": 15 }, "dryRun": false }' ``` ## Response ```json { "success": true, "mode": "send", "message": "Webhook delivered successfully", "validation": { "ok": true, "errors": [], "warnings": [] }, "request": { "url": "https://deinkunde.com/webhook", "method": "POST", "timeoutSeconds": 15, "headers": {}, "bodyPreview": "...", "bodySize": 256 }, "response": { "reachable": true, "ok": true, "statusCode": 200, "statusText": "OK", "durationMs": 150, "headers": {}, "bodyPreview": null, "bodySize": null } } ``` HTTP 429 responses are treated as "reachable but rate-limited" (success: true). ## Common errors - `401 Unauthorized` when not authenticated - `400 Bad Request` when config is invalid for the given type - `400 Bad Request` when a custom header in `config.headers` / `config.webhookHeaders` is not allowed: `Host` answers `webhookHostHeaderForbidden`; a name that is not a valid HTTP header name, a value with a line break or another control character, and the headers the sender sets itself (`Content-Length`, `Transfer-Encoding`, `Connection`, `Keep-Alive`, `Upgrade`, `TE`, `Trailer`, `Expect`, `Proxy-Connection`) answer `invalidRequestBody` with the header in `issues[].path`. `Authorization` is allowed.
### Update Notification Channel
URL: https://docs.uptimeify.io/api/notification-channels/update-notification-channel
Description: Updates a notification channel.
Summary: `PATCH /api/notification-channels/:id` Config is **merged** with existing secrets, preserving encrypted fields that are not provided, as long as the channel keeps its `type`. **Headers:** `config.headers` / `config.webhookHeaders` replace the stored list (a header you leave out is removed). A header with value `null` or `""` keeps its stored value, so you can send back the names a read returned without knowing the values. New values are stored encrypted. **Changing `type`** is different: the stored config belongs to the old channel type, so it is discarded entirely and the config is **rebuilt from the `config` in this request**. A `type` change therefore requires `config` (otherwise `400`), and secrets of the old type do not carry over. ## Request Body (all optional) | Field | Type | Description | |-------|------|-------------| | `type` | string | Channel type, one of the [supported types](/api/notification-channels/create-notification-channel#channel-types). Requires `config`. | | `name` | string | Display name, 1 to 100 characters | | `config` | object\|string | Merged with existing secrets (same type) or replaces the config entirely (type change). JSON object or JSON string of at most 20 kB. | | `delaySeconds` | number | Delay before sending, integer 0 to 86400 | | `conditions` | object\|string\|null | Alert conditions, JSON object or JSON string of at most 20 kB | | `allowedPackageTypes` | string[]\|null | Package types this channel applies to, max 50 entries | | `isActive` | boolean | Whether the channel is active | `delaySeconds` runs on its own timer for this channel, starting from the moment this channel would notify, independent of any other channel on the same alert. If a maintenance window starts before that time elapses, or the incident is already resolved by then, nothing is delivered on this channel. `priority` has been removed from channel configuration. A request that still sends it is accepted and the field is simply ignored, so existing integrations keep working unchanged. ## Example (cURL) ```bash curl -X PATCH "$BASE_URL/api/notification-channels/1" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated Email Channel", "isActive": true }' ``` ## Common errors - `400 Bad Request` with `data.code` `invalidRequestBody` when an `email` or `sms` channel carries a recipient the delivery path could never accept. Checked for `type: email` in `config.to` and `config.email`, and for `type: sms` in `config.to`, `config.phoneNumbers` and `config.phoneNumber`; a comma-separated string and an array are both read as a list and every entry is checked, and the message names the first offending value. An email recipient needs exactly one `@` with something on both sides and no spaces, the form `Name ` is allowed; an SMS recipient must be E.164, a `+`, a digit 1-9, then 7 to 14 more digits, with no spaces, dashes or brackets. These are the delivery path's own rules, so a value refused here could never have received an alert. A channel with NO recipient of its own stays valid: delivery then falls back to the customer's or the organization's stored address. Only `email` and `sms` are checked; on every other type these keys mean something else. - `400 Bad Request` with `data.code` `smsCountryNotAllowed` when an `sms` channel carries a number outside the EU/EEA, Switzerland and the UK. Alert SMS only go to these countries; the check is on the country calling code (`+49`, `+44`, `+353`, ...). The alert worker applies the same list again before sending, so an older channel with another country is skipped and shows as skipped in the delivery log. - `400 Bad Request` with `data.code` `invalidRequestBody` when a target URL in `config` is not a parseable `http`/`https` URL, or points at a private, loopback or link-local address, at `localhost`, at a reserved private-use name (`.local`, `.internal`, `.home.arpa`) or at a single-label host. Every top-level `config` string starting with…
### Connected apps (OAuth connections)
URL: https://docs.uptimeify.io/api/oauth-connections
Description: List and revoke the OAuth/MCP applications connected to your account, such as Claude's remote MCP connector.
Summary: Uptimeify lets you connect third-party apps (like Claude Desktop / Claude.ai) via [MCP OAuth](/api/mcp). These two endpoints let the signed-in user list and revoke their own connections. They power the **Settings → Connected apps** page in the dashboard. Both endpoints are **session-authenticated** (browser cookie), not token-based: they are not part of the `wsm_`/`wsma_` API-token surface, and every operation is strictly scoped to the caller's own connections. ## How clients connect A client registers in one of two ways: with a **Client ID Metadata Document** (CIMD, preferred), where the `client_id` is an HTTPS URL that serves the client's own metadata, or through **Dynamic Client Registration** at `/api/auth/oauth2/register`. The authorization server metadata at `/.well-known/oauth-authorization-server` lists every endpoint; authorization and token exchange live under `/api/auth/oauth2/`. Access tokens are signed JWTs bound to the resource `https://uptimeify.io/mcp` and are valid for one hour. With `offline_access` the client also receives a refresh token, valid for seven days and replaced on every use. Revoking a connection takes effect immediately, also for an access token that has not expired yet. ## Scopes A connection carries scopes, and each one covers exactly one area of your monitoring data. Sixteen scopes exist in total: eight read scopes, the collective alias `mcp:read` for three of them, and seven write scopes that let the connection change data in that area instead of just viewing it. ### Read scopes | Scope | Covers | Tools it unlocks | | --- | --- | --- | | `mcp:monitors:read` | Your monitors and their current state | `list_monitors`, `monitor_status` | | `mcp:incidents:read` | Incidents across your monitors | `list_incidents` | | `mcp:checks:read` | Check history and uptime figures | `check_history`, `uptime_summary` | | `mcp:alerts:read` | Notification channels, escalation configuration, alert history | `list_alert_channels`, `alert_history` | | `mcp:statuspages:read` | Status pages and maintenance windows | `list_status_pages`, `list_maintenance_windows` | | `mcp:organization:read` | Organization profile, customers and users | `get_organization`, `list_users`, `list_customers` | | `mcp:billing:read` | Billing and SMS usage | `billing_summary` | | `mcp:im:read` | Incident Management: incidents with timeline, who is on call, teams and on-call schedules, people by name only | `list_im_incidents`, `get_im_incident`, `who_is_on_call`, `list_im_teams`, `get_im_team`, `list_im_schedules`, `get_im_schedule` | | `mcp:read` | Collective alias, covers the three operational areas above | the five tools of those three areas | `mcp:read` is the scope a client requests when it asks for read access without naming an area, and it is what connections made before granular scopes existed carry. It is frozen to the three operational areas that existed when it was introduced (monitors, incidents, check history) and does not grow when a new area is added: the five newer read areas (alerts, status pages, organization, billing, Incident Management) must be requested by name, and only then does the consent screen offer them. Those connections are unchanged. ### Write scopes | Scope | Covers | | --- | --- | | `mcp:monitors:write` | Create, change and delete monitors, including deleting a monitor and its history | | `mcp:incidents:write` | Create, change and delete incidents, including posting incident updates that subscribers receive | | `mcp:maintenance:write` | Create, change and delete maintenance windows; alerts are suppressed for the monitors a window covers | | `mcp:statuspages:write` | Create, change and delete status pages, including their design and custom domains; subscriber addresses stay out of reach | | `mcp:alerts:write` | Create, change and delete alert channels; deleting a channel stops alerts from reaching it | | `mcp:organization:write` | Create, change and delete customers (with their watched domains and IP addresse…
### Organization & Billing
URL: https://docs.uptimeify.io/api/organization
Description: Path-based organization endpoints use organizationPublicId UUIDs.
Summary: ## Endpoints - [Get Organization Details](/api/organization/get-organization-details) - [Update Organization](/api/organization/update-organization) - [List Package Configs](/api/organization/list-package-configs) - [Upsert Package Config](/api/organization/upsert-package-config) - [Delete Package Config](/api/organization/delete-package-config) - [Get Billing Details](/api/organization/get-billing-details) - [Update Billing Details](/api/organization/update-billing-details) - [List Invoices](/api/organization/list-invoices) - [List Audit Log](/api/organization/list-audit-events) - [Error codes and known API pitfalls](/api/error-codes-and-known-pitfalls)
### Sender Domain
URL: https://docs.uptimeify.io/api/organization-sender-domain
Description: Send your organization's emails from your own domain through Uptimeify's mail infrastructure, without running your own SMTP server. Enterprise feature, enabled per organization by Uptimeify. Admin-only.
Summary: Your organization's alert, report and status page emails can go out from your own domain (for example `alerts@status.example.com`) through Uptimeify's mail provider. You add the domain, publish the DNS records the API returns, and once they verify, mail is sent from your address. This is an Enterprise feature. Until Uptimeify has enabled it for your organization, every endpoint on this page answers `403` with `data.code` `senderDomainNotEnabled`. ## Which sender is used 1. Your own SMTP server, when one is configured ([Organization SMTP](/api/organization-smtp)). It always wins. 2. Your sender domain, while its `status` is `verified`. 3. Otherwise the Uptimeify sender. This includes a domain that loses its verification later: mail keeps arriving, from the Uptimeify sender, until the DNS records are back. Your organization's admins get one email when that happens. Emails between Uptimeify and your organization (billing, account notices) always come from Uptimeify. ## Authentication and permissions `admin` role. Closed to API tokens with scopes, customer-bound tokens and agent tokens: use a token without scopes or a session. ```bash BASE_URL="https://uptimeify.io" TOKEN="" ``` ## The sender domain object | Field | Type | Description | |-------|------|-------------| | `domain` | string | The sender domain, lower case. | | `fromEmail` | string | Sender address, always on `domain`. | | `fromName` | string | Sender display name. | | `replyTo` | string\|null | Reply-to address. | | `status` | string | `pending` (DNS records not verified yet), `verified` (mail is sent from this domain), `failed` (was verified, is not anymore). | | `dnsRecords` | array | The records to publish: `type`, `hostname`, `fqdn`, `content`, `status` (`active`, `pending`, `failed`), `purpose`, `required` (needed for verification). | | `lastCheckedAt` | string\|null | Last check, ISO 8601 UTC. | | `verifiedAt` | string\|null | When the domain last became verified. | | `lastError` | string\|null | What the last check reported while not verified. | | `createdAt`, `updatedAt` | string | ISO 8601 UTC. | ## Get the sender domain `GET /api/organization/sender-domain` ```bash curl "$BASE_URL/api/organization/sender-domain" -H "Authorization: Bearer $TOKEN" ``` ```json { "domain": "status.example.com", "fromEmail": "alerts@status.example.com", "fromName": "Example Alerts", "replyTo": null, "status": "pending", "dnsRecords": [ { "type": "CNAME", "hostname": "lm1._domainkey", "fqdn": "lm1._domainkey.status.example.com", "content": "lm1._domainkey.example.lmta.net", "status": "pending", "purpose": "dkim_primary", "required": true } ], "lastCheckedAt": null, "verifiedAt": null, "lastError": null, "createdAt": "2026-11-09T10:00:00.000Z", "updatedAt": "2026-11-09T10:00:00.000Z" } ``` `404` with `data.code` `senderDomainNotConfigured` while no domain is set. ## Set the sender domain `PUT /api/organization/sender-domain` Adds the domain, or changes it. A new domain starts as `pending` with fresh `dnsRecords`; a previous domain is removed. Sending the same domain again changes only the sender fields and keeps the verification. | Field | Type | Required | Description | |-------|------|----------|-------------| | `domain` | string | yes | A domain name. A subdomain such as `status.example.com` is recommended. Lower-cased; a trailing dot is dropped. | | `fromEmail` | string | yes | Sender address. Must be exactly on `domain` (`alerts@status.example.com`, not `alerts@example.com`). | | `fromName` | string | yes | Display name, 1-200 characters. | | `replyTo` | string\|null | no | Reply-to address; `null` clears it. | Unknown fields are rejected. ```bash curl -X PUT "$BASE_URL/api/organization/sender-domain" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "domain": "status.example.com", "fromEmail": "alerts@status.example.com", "fromName": "Example Alerts" }' ``` Answers `200` with the sender domain object. ## Check the DNS records no…
### Organization SMTP
URL: https://docs.uptimeify.io/api/organization-smtp
Description: Configure custom SMTP settings so your organization's notification emails are sent through your own mail server. All SMTP endpoints require admin role.
Summary: ## Authentication All endpoints accept API bearer tokens or session cookies: ```bash BASE_URL="https://uptimeify.io" TOKEN="" ``` ## Endpoints - [Test SMTP Connection](/api/organization-smtp/test-smtp) - [Get SMTP Send Logs](/api/organization-smtp/get-smtp-logs)
### Get SMTP Send Logs
URL: https://docs.uptimeify.io/api/organization-smtp/get-smtp-logs
Description: Returns recent SMTP send event logs from Redis. Admin-only.
Summary: `GET /api/organization/smtp/logs` ## Query Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `limit` | number | 100 | Max events to return (1-500) | | `envelope` | string | none | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ## Example (cURL) ```bash curl -X GET "$BASE_URL/api/organization/smtp/logs?limit=50&envelope=items" \ -H "Cookie: $SESSION_COOKIE" \ -H "Accept: application/json" ``` ## Response ```json { "items": [ { "type": "smtp_send", "timestamp": "2026-04-15T12:00:00.000Z", "to": "admin@deinkunde.com", "subject": "Website Down: deinkunde.com", "status": "sent" } ], "total": 1, "page": 1, "perPage": 1 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form (`{ "events": [...] }`), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. Returns an empty list (`"items": []`; in the current form `{ "events": [] }`) if no logs exist or on Redis errors (fails open). ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` when not an admin
### Test SMTP Connection
URL: https://docs.uptimeify.io/api/organization-smtp/test-smtp
Description: Tests the SMTP configuration by sending a test email. All parameters are optional. When omitted, stored config values are used. This allows testing new credentials before saving them. Admin-only.
Summary: `POST /api/organization/smtp/test` The test also updates the SMTP config's `lastTestedAt`, `lastTestStatus`, and `lastTestError` fields. ## Request Body (all optional) | Field | Type | Description | |-------|------|-------------| | `toEmail` | string | Recipient email address (max 320 chars). Defaults to current user's email. | | `subject` | string | Email subject (1-200 chars). Defaults to `SMTP Test ()`. | | `message` | string | Email body (1-2000 chars). Defaults to a standard test message. | | `host` | string\|null | SMTP server hostname (1-255 chars). Overrides stored config. | | `port` | number\|null | SMTP server port (1-65535). Overrides stored config. | | `username` | string\|null | SMTP username (1-200 chars). Overrides stored config. | | `password` | string\|null | SMTP password (1-500 chars). Overrides stored config (not persisted). | | `tlsMode` | string\|null | `ssl`, `starttls`, or `none`. Overrides stored config. | | `fromName` | string\|null | Sender display name (1-200 chars). Overrides stored config. | | `fromEmail` | string\|null | Sender email address (max 320 chars). Overrides stored config. | | `replyTo` | string\|null | Reply-to email address (max 320 chars). Overrides stored config. | ## Example (cURL): Using stored config ```bash curl -X POST "$BASE_URL/api/organization/smtp/test" \ -H "Cookie: $SESSION_COOKIE" \ -H "Content-Type: application/json" \ -d '{}' ``` ## Example (cURL): Testing new credentials ```bash curl -X POST "$BASE_URL/api/organization/smtp/test" \ -H "Cookie: $SESSION_COOKIE" \ -H "Content-Type: application/json" \ -d '{ "host": "smtp.deinkunde.com", "port": 587, "tlsMode": "starttls", "username": "alerts@deinkunde.com", "password": "secret-password", "fromName": "Uptimeify Alerts", "fromEmail": "alerts@deinkunde.com", "toEmail": "admin@deinkunde.com" }' ``` ## Response (success) ```json { "success": true, "messageId": "" } ``` ## Common errors - `400 Password must be re-entered when the SMTP host changes` (`data.code: smtpPasswordRequiredForNewHost`) when the request sends a `host` that differs from the stored one but no `password`: the stored password is only ever sent to the stored host - `400 Missing recipient email (toEmail)` when no recipient and user has no email - `400 SMTP config incomplete (host/port required)` when host or port is missing - `400 SMTP config incomplete (username required)` when username is needed but missing - `400 SMTP password missing (username is set)` when password is needed but missing - `400 SMTP config incomplete (fromEmail required)` when fromEmail is missing - `403 Forbidden` when not an admin - `502 Failed to send SMTP test email` when the SMTP connection fails
### Apply Report Default
URL: https://docs.uptimeify.io/api/organization/apply-report-default
Description: Writes a package's monthlyReportsDefault onto every existing customer currently on that package, once.
Summary: `POST /api/package-configs/:packageType/apply-report-default` The organization comes from your session or API token. The path `POST /api/organizations/:id/package-configs/:packageType/apply-report-default` does the same for the organization `:id`; it is deprecated and removed on 2027-01-18. [Upsert Package Config](/api/organization/upsert-package-config)'s `monthlyReportsDefault` is a **template**: it only seeds `monthlyReportsEnabled` for customers created from then on. Saving the package config never rewrites customers who already exist on it, on purpose, a configuration save must not silently mutate customer rows. This endpoint is the explicit, one-off action for the other case: propagate the package's current `monthlyReportsDefault` onto every customer that already holds that package, right now. This is a single bulk `UPDATE`, not a loop with per-customer error isolation like [Bulk Actions](/api/customers/bulk-actions): it writes one boolean column with no cascade and no side effects, so per-row isolation buys nothing here. Either the whole set is written, or the request fails before anything is written. ## Query parameter `organizationId` (global admins) `organizationId` (positive integer, optional): apply the default in this organization instead of your own. Only global admins may name a foreign organization; anyone else gets `403 forbidden`. Naming your own organization behaves like leaving the parameter out. This is the successor for the organization `:id` of the deprecated path. ## Path parameter `:id` (deprecated path only) `:id` is the organization's **numeric** `id`, the same integer `id` field returned by [Get Organization Details](/api/organization/get-organization-details). This is narrower than the sibling package-config routes, which also resolve `:organizationPublicId` (a UUID). This endpoint does not: it parses the path segment with `Number(...)` directly and rejects anything that is not a positive integer with `400 invalidRequestBody`. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/package-configs/pro/apply-report-default" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` No request body. ## Response ```json { "updated": 42 } ``` `updated` is the number of customer rows written. A customer "holds" the package if its `packageId` matches this package config's id, or, for customers that were never assigned an id, if its `packageType` string matches. Customers that only happen to share the same `packageType` string without holding this exact config are not included. ## Common errors - `400 invalidRequestBody` `:id` is not a positive integer, or `:packageType` is missing - `400 invalidOrganizationId` `organizationId` is not a positive integer - `400 organizationIdRequired` the session or token has no organization (path without `:id`) - `401 unauthorized` you are not logged in - `403 forbidden` you are not an admin of this organization and not a global admin - `403 customerScopedTokenForbidden` when called with a customer-scoped API token; this is an organization-wide action and requires an organization-scoped token or a session - `404 notFound` no package config with this `packageType` exists for this organization Authorization note: - Write access is required (organization admin of the target organization, or global admin). - A customer-scoped API token is refused outright. This endpoint writes across every customer holding the package, so there is no customer dimension to narrow it down to; a token bound to a single customer must not reach the rest of the organization.
### Cancel Scheduled Quota Change
URL: https://docs.uptimeify.io/api/organization/cancel-pending-quota-change
Description: Cancels a quota reduction that was scheduled for the end of the current billing period, so the organization keeps its current plan. Answers cancelled:false, not 404, when nothing is scheduled.
Summary: `DELETE /api/organizations/:organizationPublicId/pending-quota-change` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" ORG_ID="" curl -X DELETE "$BASE_URL/api/organizations/$ORG_ID/pending-quota-change" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` Notes: - This endpoint takes no request body. It closes whichever quota reduction is currently scheduled for the organization; there is never more than one. - From 1 January 2027, a quota reduction sent without `quotaChangeEffective: "immediately"` does not take effect immediately (until then a reduction on a monthly plan applies immediately, a yearly one is scheduled): it is scheduled for the end of the current billing period and is returned as `pendingQuotaChange` (see [Update Organization](/api/organization/update-organization) and [Get Organization Details](/api/organization/get-organization-details)). This endpoint is what calls it off before it fires. - **This is the only way to keep the current plan.** Direction is classified against the organization's *current*, still higher tier, so re-sending the current tier through `PATCH` counts as an unchanged request and leaves the scheduled reduction in place. Only a genuine price increase supersedes one, and that changes the plan rather than restoring it. - Cancelling is free and always allowed until the change applies. Afterwards there is nothing left to cancel: the reduction is already the organization's plan, and going back up is an ordinary quota increase through [Update Organization](/api/organization/update-organization). - Requires organization write access (organization admin or global admin) from an unrestricted session or token, the same authorization as [Update Organization](/api/organization/update-organization). A customer-scoped API token cannot call this endpoint, even with `admin`-level role, because cancelling changes what the organization pays from the next period onwards. ## Response ```json { "cancelled": true } ``` | Value | Meaning | | --- | --- | | `true` | A scheduled reduction was open and has been cancelled. The organization keeps its current plan. | | `false` | Nothing was scheduled, so nothing changed. **This is a success, not an error**, the endpoint is deliberately idempotent so that a repeated call (a double-clicked button, a retried request) does not surface a failure. | ## Common errors - `401 Unauthorized` (`data.code: unauthorized`) when you are not logged in - `400 Invalid Organization identifier` when `:organizationPublicId` is neither a legacy integer id nor a valid UUID public identifier - `403 Forbidden` (`data.code: forbidden`) when you do not have write access to the organization - `403 Forbidden` (`data.code: customerScopedTokenForbidden`) when called with a customer-scoped API token; this is an organization-wide action and requires an organization-scoped token or a session - `404 Organization not found` (no `data.code`) when `:organizationPublicId` does not resolve to an existing organization Note that there is no "nothing to cancel" error, that case is `200` with `cancelled: false`. See [Error Codes](/api/error-codes-and-known-pitfalls) for the full list.
### Delete Package Config
URL: https://docs.uptimeify.io/api/organization/delete-package-config
Description: Deletes a package config for an organization. Deletion is only allowed if no customers are currently assigned to that package. The package is resolved directly from the path parameter, so values like test1 work as long as they match the stored packageType.
Summary: `DELETE /api/package-configs/:packageType` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X DELETE "$BASE_URL/api/package-configs/pro" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` Notes: - The organization is derived automatically from your authenticated session or API token. - The legacy route `DELETE /api/organizations/:organizationPublicId/package-configs/:packageType` remains supported for compatibility. - The plural org-less alias `DELETE /api/organizations/package-configs/:packageType` is also supported. - Global admins need an active organization context in the authenticated session for the org-less route. - The in-use check evaluates each customer's package assignment, not the package name. Customers that merely carry the same `packageType` string without being assigned to this config do not block deletion. ## Response ```json { "success": true } ``` ## Common errors - `404 Package not found` when the config does not exist - `409 Package is still in use by customers` when customers are assigned to this package - `400 Package type is required` when `:packageType` is missing - `400 Organization ID is required in the authenticated session` when no organization can be derived from the current session/token - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the organization Authorization note: - Write access is required (organization admin or global admin).
### Download Data Export
URL: https://docs.uptimeify.io/api/organization/download-data-export
Description: Issues a short-lived download URL for a finished organization data export.
Summary: `GET /api/organization/data-export/{exportId}/download` Returns a presigned URL for the export ZIP. The URL is valid for 5 minutes; the object key itself is never exposed and the storage bucket is not browsable, so knowing an export id is not access, an authenticated administrator of the owning organization is. ## Query parameters | Parameter | Type | Description | | --- | --- | --- | | `redirect` | `1` | Respond with `302` to the presigned URL instead of returning JSON. Convenient for `curl -L` and browser links. | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" EXPORT_ID="0f0f2f6a-2b3b-4a2f-9a7c-3e5f8c1d2b44" # Straight to the file curl -L -o export.zip \ "$BASE_URL/api/organization/data-export/$EXPORT_ID/download?redirect=1" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "url": "https://..your-objectstorage.com/data-exports/org-12/0f0f2f6a-...zip?X-Amz-Signature=...", "expiresInSeconds": 300, "sizeBytes": 18446721, "filename": "uptimeify-export-0f0f2f6a-2b3b-4a2f-9a7c-3e5f8c1d2b44.zip" } ``` Each call increments `downloadCount` and updates `lastDownloadedAt` on the export record. ## Common errors - `400 User must belong to an organization` when no organization can be derived from the session or token - `400 Invalid Export identifier` when `{exportId}` is not shaped like a UUID - `401 Unauthorized` when you are not authenticated - `403 Forbidden` when your role cannot administer the organization - `404 Export not found` when the id does not belong to your organization - `409 Export is not downloadable` (`data.code: exportNotReady`) while the export is queued, generating or failed - `410 Export download window has expired` (`data.code: exportExpired`) after the 7-day window
### Export Audit Log
URL: https://docs.uptimeify.io/api/organization/export-audit-log
Description: Downloads your organization's audit log for one period as a CSV file, sign-ins included.
Summary: `GET /api/organization/audit/export` Returns the audit log of your organization for one period as a CSV file. The log records administrative actions (every write through the dashboard or the API, with old and new value where the action records it) and sign-in events: successful and failed sign-ins of existing accounts, sign-outs, password resets, password changes and ended sessions. Entries are kept for 12 months and cannot be changed or deleted through the application. Only organization administrators can call it, with a session or an organization-wide API token whose issuer is an admin. Connected apps (MCP agents) cannot. Every export is itself recorded in the audit log. ## Query parameters | Parameter | Type | Description | | --- | --- | --- | | `from` | ISO 8601 UTC | Start, inclusive. Default: 30 days before `to`. | | `to` | ISO 8601 UTC | End, exclusive. Default: now. | One export spans at most 366 days and at most 100,000 entries. Split a longer period into several exports. The export only contains entries that are still stored. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -o audit-log.csv \ "$BASE_URL/api/organization/audit/export?from=2026-01-01T00:00:00.000Z&to=2026-04-01T00:00:00.000Z" \ -H "Authorization: Bearer $TOKEN" ``` ## Response `200` with `Content-Type: text/csv; charset=utf-8`, a `Content-Disposition` attachment and `Cache-Control: no-store`. Rows are sorted oldest first; entries with the same timestamp keep a stable order. The file is UTF-8 without BOM: in Excel open it via Data > From Text/CSV so umlauts show correctly. ```csv "time","actor","agent","action","auth","summary","target","changes","ip","user_agent","request_id" "2026-03-02T08:14:03.512Z","admin@example.com","no","auth.login.succeeded","password","Signed in","user:Xk2f9","","","","" "2026-03-02T08:15:40.101Z","admin@example.com","no","websites.update","","Website updated","website:46","[{""field"":""checkInterval"",""from"":5,""to"":1}]","","","9b1e2c4a" ``` | Column | Content | | --- | --- | | `time` | When it happened, ISO 8601 UTC | | `actor` | Email address of the acting user, or their ID; empty for a failed sign-in and a requested password reset | | `agent` | `yes` when a connected app (MCP agent) acted on behalf of the user | | `action` | Event type, for example `websites.update` or `auth.login.failed` | | `auth` | Sign-in events only: method and, for a failed sign-in, the reason code as `method:reason` (for example `password:INVALID_EMAIL_OR_PASSWORD`), otherwise just the method (`password`, `password_mfa`, `sso`); empty for all other events | | `summary` | Short description | | `target` | Affected object as `type:id`, for sign-in events the account | | `changes` | Changed fields as JSON (`field`, `from`, `to`); secrets only as changed | | `ip`, `user_agent` | Only when a connected app (MCP agent) acted; empty otherwise, sign-in events included | | `request_id` | Correlation ID of the request | Every cell is quoted. A cell that starts with `=`, `+`, `-` or `@`, also after leading whitespace, gets a leading `'`, so spreadsheet applications show it as text instead of running it as a formula. ## Common errors - `400 Invalid query` (`data.code: invalidRequestBody`) when `from` or `to` is not an ISO 8601 timestamp in UTC (ending in `Z`) - `400` (`data.code: invalidDateRange`) when `from` is not before `to` - `400` (`data.code: auditExportRangeTooLarge`) when the period is longer than 366 days or holds more than 100,000 entries - `400 User must belong to an organization` when no organization can be derived from the session or token - `401 Unauthorized` when you are not authenticated - `403 Forbidden` when your role is not admin
### Get Billing Details
URL: https://docs.uptimeify.io/api/organization/get-billing-details
Description: Returns billing information and payment methods for the organization in your authenticated session.
Summary: `GET /api/organization/billing` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/organization/billing" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` Notes: - The organization is derived automatically from your authenticated session or API token. - The legacy route `GET /api/organizations/:organizationPublicId/billing` remains supported for compatibility. - The plural org-less alias `GET /api/organizations/billing` is also supported. - Global admins need an active organization context in the authenticated session for the org-less route. ## Response ```json { "billingEmail": "billing@deinkunde.com", "paymentMethod": "mollie" } ``` ## Common errors - `400 Organization ID is required in the authenticated session` when no organization can be derived from the current session/token - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the organization
### Get Organization Details
URL: https://docs.uptimeify.io/api/organization/get-organization-details
Description: Returns details of the organization from your authenticated session.
Summary: `GET /api/organization` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/organization" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` Notes: - The organization is derived automatically from your authenticated session or API token. - The legacy route `GET /api/organizations/:organizationPublicId` remains supported for compatibility. - The plural org-less alias `GET /api/organizations` is also supported. - Global admins need an active organization context in the authenticated session for the org-less route. - `emailLanguage` (`de`, `en` or `da`) is the organization's default language for e-mails and text messages. Every member receives it; customers without their own `emailLanguage` follow it. - `contractEmail` is the address that receives notices of changes to the terms, the DPA and the privacy policy; `null` means every admin receives them. Like the other billing fields it is only returned to organization admins and global admins, other members receive `null`. - Billing fields, including the billing address (`companyName`, `street`, `postalCode`, `city`, `country`), `vatId`, the `quota*` fields and `pendingQuotaChange`, are only present for an organization admin or a global admin. Other members receive the response without them. ## Response ```json { "id": 1, "name": "My Org", "emailLanguage": "de", "companyName": "My Company GmbH", "street": "Sample St. 1", "postalCode": "12345", "city": "Berlin", "country": "DE", "vatId": "DE123456789", "billingEmail": "billing@deinkunde.com", "contractEmail": "contracts@deinkunde.com", "createdAt": "2023-01-01T00:00:00.000Z", "pendingQuotaChange": { "effectiveAt": "2026-08-01T00:00:00.000Z", "quotaWebsitesLimit": 25, "quotaSmsIncluded": 100, "quotaMonthlyPriceCents": 6900 } } ``` `pendingQuotaChange` describes a quota reduction that has been requested but does not take effect until the end of the current billing period (a reduction requested with `quotaChangeEffective: "period_end"`, the default). It is `null` when nothing is scheduled, which is the normal case. | Field | Meaning | | --- | --- | | `effectiveAt` | The first instant at which the new plan applies: for a monthly billing cycle the start of the next month (00:00 Europe/Berlin from 1 January 2027, e.g. `2027-01-31T23:00:00.000Z` for 1 February; 00:00 UTC for reductions scheduled until 31 December 2026), the end of the paid term for a yearly one. | | `quotaWebsitesLimit` | The monitor limit that will apply from then on. `null` means no limit. | | `quotaSmsIncluded` | The included SMS allowance that will apply from then on. | | `quotaMonthlyPriceCents` | The monthly price that will apply from then on, in cents. | While a change is pending, the organization's own `quota*` fields still describe the **current, higher** plan, that is the point of the clause, and billing continues at that plan for the whole period. Use [Cancel Scheduled Quota Change](/api/organization/cancel-pending-quota-change) to call it off, or [Update Organization](/api/organization/update-organization) to raise the plan instead. ## Common errors - `400 Organization ID is required in the authenticated session` when no organization can be derived from the current session/token - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the organization
### List Audit Log
URL: https://docs.uptimeify.io/api/organization/list-audit-events
Description: Returns the audit log of your organization: who did what and when, filterable by period, area and outcome.
Summary: `GET /api/organization/audit` Returns the logged actions in your organization, newest first. Without `since` the list covers the last 30 days. Entries are kept for 12 months; older ones within that period through `since` or the [export](/api/organization/export-audit-log). ## Access Organization admins only, with a session or an organization-wide API token whose issuer is an admin. Other roles get `403 forbidden`. Agent tokens (connected apps) are refused for this path. The organization is derived from the session or token; you cannot read another organization's log. ## Query parameters | Parameter | Default | Description | |-----------|---------|-------------| | `since` | 30 days before now | Unix time in milliseconds, inclusive lower bound. Pass an earlier value to read further back. | | `until` | none | Unix time in milliseconds, inclusive upper bound: an entry at exactly `until` is included. | | `limit` | `100` | 1 to 500. | | `offset` | `0` | 0 to 50000. | | `sortBy` | `ts` | `ts`, `actor`, `status`, `summary` or `durationMs`. | | `sortOrder` | `desc` | `asc` or `desc`. | | `q` | none | Case-insensitive text filter over area, summary and the actor's email or user id. | | `area` | none | Exact area, e.g. `websites`. | | `success` | none | `true` or `false`. Entries without an outcome are left out when this is set. | | `envelope` | none | `items` answers `{ items, total, page, perPage }`. | `total` counts the entries after all filters. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/organization/audit?since=1759276800000&limit=50&envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "items": [ { "id": "4f1c2a9e-8b7d-4c3e-9f20-6a5b4c3d2e1f", "ts": 1761126000000, "organizationId": 1, "area": "websites", "summary": "Websites updated", "actor": { "email": "admin@youragency.com", "userId": "u_123" }, "success": true, "durationMs": 42, "type": "websites.update", "method": "PATCH", "route": "/api/websites/[id]", "statusCode": 200, "resourceType": "websites", "resourceId": "17", "changes": [{ "field": "name", "from": "Shop", "to": "Shop (live)" }] } ], "total": 1, "page": 1, "perPage": 50 } ``` | Field | Description | |-------|-------------| | `ts` | Unix time in milliseconds. | | `summary` | Short English description. | | `route` | Route template, never the raw path. | | `actor` | Who acted, or `null`. | | `ipAddress`, `userAgent` | Only recorded for requests made by a connected app (MCP agent). | | `agent` | Set when a connected app acted on behalf of the actor. | | `auth` | `{ method, reason }`, only on sign-in events (`type` starts with `auth.`). `method`: `password`, `password_mfa` or `sso` for a sign-in; `one`, `others` or `all` for `auth.sessions.revoked`; otherwise `null`. `reason`: error code of a failed sign-in (e.g. `INVALID_EMAIL_OR_PASSWORD`), otherwise `null`. | | `changes` | What became what, where the action records it. Secret values are not logged (`redacted: true`). | **List form:** with `envelope=items` the list comes as `{ items, total, page, perPage }` (`perPage` is `limit`, `page` is `floor(offset / limit) + 1`). Without the parameter the endpoint still answers in the previous form `{ "events": [...], "pagination": { "limit", "offset", "total" } }`; it is deprecated, from 2027-01-18 `{ items, ... }` is the default. ## Sign-in events Besides requests, the log records these `type` values: `auth.login.succeeded`, `auth.login.failed` (known accounts only; `actor` is `null`), `auth.logout`, `auth.password_reset.requested`, `auth.password_reset.completed`, `auth.password.changed`, `auth.sessions.revoked` and `app_link.redeemed` (sign-in to the app with a QR code). The type `audit.export` records each [audit log export](/api/organization/export-audit-log) with its period and row count. Sign-in events never carry `ipAddress` or `userAgent`; only account, time, method and reason code are stored. ## Comm…
### List Data Exports
URL: https://docs.uptimeify.io/api/organization/list-data-exports
Description: Returns the recent data export requests of your organization with status, size, retention window and expiry.
Summary: `GET /api/organization/data-export` Returns the 20 most recent export requests, newest first. Poll this (or `GET /api/organization/data-export/{exportId}`) while an export is `queued` or `generating`. ## Response ```json { "exports": [ { "id": "0f0f2f6a-2b3b-4a2f-9a7c-3e5f8c1d2b44", "status": "ready", "format": "json_csv", "includeCheckHistory": true, "recipientEmails": ["admin@youragency.com"], "sizeBytes": 18446721, "retentionCutoff": "2025-03-30T09:12:44.101Z", "expiresAt": "2026-08-06T09:19:02.884Z", "downloadCount": 1, "lastDownloadedAt": "2026-07-30T10:02:11.900Z", "errorMessage": null, "manifest": { "generatedAt": "2026-07-30T09:12:52.006Z", "retentionCutoff": "2025-03-30T09:12:44.101Z", "includeCheckHistory": true, "packages": [ { "packageType": "fullservice", "displayName": "Full Service", "dataRetentionMonths": 16, "cutoff": "2025-03-30T09:12:44.101Z" } ], "sections": [ { "path": "customers/customers", "rows": 42 }, { "path": "monitors/websites", "rows": 311 }, { "path": "checks/website-checks", "rows": 100000, "truncated": true } ], "redactedFields": ["passwords and passphrases", "webhook secrets and signing keys"] }, "createdAt": "2026-07-30T09:12:44.101Z", "startedAt": "2026-07-30T09:12:45.010Z", "completedAt": "2026-07-30T09:19:02.884Z" } ], "cooldownHours": 6 } ``` ## Statuses | Status | Meaning | | --- | --- | | `queued` | Accepted, waiting for the builder | | `generating` | The bundle is being built | | `ready` | Downloadable until `expiresAt` | | `failed` | Build failed; `errorMessage` carries the reason | | `expired` | Download window closed, the file has been deleted | ## Single export `GET /api/organization/data-export/{exportId}` returns one export in the same shape (without the `exports` wrapper). **Deprecated field:** `error` is still sent next to `errorMessage` until it is removed on 2027-01-18. Read `errorMessage`. ## Common errors - `400 User must belong to an organization` when no organization can be derived from the session or token - `400 Invalid Export identifier` when `{exportId}` is not shaped like a UUID - `401 Unauthorized` when you are not authenticated - `403 Forbidden` when you cannot read the organization - `404 Export not found` when the id does not belong to your organization
### List Invoices
URL: https://docs.uptimeify.io/api/organization/list-invoices
Description: Lists all invoices for the organization (Mollie).
Summary: `GET /api/mollie/invoices` ## Query Parameters | Parameter | Type | Default | Description | |---|---|---|---| | `envelope` | string | none | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET \ "$BASE_URL/api/mollie/invoices?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` Notes: - The organization is derived automatically from your authenticated session or API token. - The legacy route `GET /api/organizations/:organizationPublicId/mollie/invoices` remains supported for compatibility. - The `pdfUrl` values in the response use the org-less download route `/api/invoices/:invoiceId/pdf`. - Downloading a PDF from `pdfUrl` answers `502` (`data.code: invoiceProviderFailed`) when the accounting provider fails or is unreachable, and `404` (`data.code: invoiceNotFound`) when the invoice does not exist. Neither is a problem with your session, so do not sign out on them. - Global admins need an active organization context in the authenticated session for the org-less route. ## Response ```json { "items": [ { "id": "inv_123456", "reference": "INV-2024-001", "status": "paid", "issuedAt": "2024-01-15T10:00:00.000Z", "netAmount": { "value": "29.99", "currency": "EUR" }, "pdfUrl": "/api/invoices/inv_123456/pdf" }, { "id": "inv_123455", "reference": "INV-2023-128", "status": "paid", "issuedAt": "2023-12-15T10:00:00.000Z", "netAmount": { "value": "29.99", "currency": "EUR" }, "pdfUrl": "/api/invoices/inv_123455/pdf" } ], "total": 2, "page": 1, "perPage": 2 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form (`{ "invoices": [...] }`), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. ## Common errors - `400 Organization ID is required in the authenticated session` when no organization can be derived from the current session/token - `401 Unauthorized` when you are not logged in - `403 Not authorized` when you cannot access the organization - `403 Only organization admins can view invoices` (`data.code: forbidden`) for editors, readonly users and responders of the organization; invoices carry the billing address, VAT id and amounts
### List Package Configs
URL: https://docs.uptimeify.io/api/organization/list-package-configs
Description: Returns all package configurations for the organization in your authenticated session. Each config also includes a usedByCustomerCount field.
Summary: `GET /api/package-configs` ## Query parameters | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `summary` | string | - | Set to `1` to add a `summary` object with usage numbers to every config. Any other value (or omitting it) returns the plain list. | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/package-configs" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` Notes: - The organization is derived automatically from your authenticated session or API token. - The legacy route `GET /api/organizations/:organizationPublicId/package-configs` remains supported for compatibility. - Global admins need an active organization context in the authenticated session for the org-less route. - `usedByCustomerCount` counts the customers actually assigned to that config, not the customers whose `packageType` string happens to match its name. ## Response ```json [ { "id": 10, "packageType": "pro", "maxUrls": 100, "maxStatusPages": null, "dataRetentionMonths": 12, "checkIntervalMinutes": 1, "checkLocations": 3, "notificationDelayMinutes": 0, "reminderDelayMinutes": 10, "alertConsecutiveChecks": 3, "alertLocationThreshold": "majority", "alertLocationThresholdCount": 2, "alertReminderInterval": 60, "enableSslCheck": true, "enableHttpsCheck": true, "enableStatusCheck": true, "enableSizeCheck": true, "enableResponseTimeCheck": true, "enableKeywordCheck": false, "enableEmailAlerts": true, "enableSmsAlerts": true, "enableWebhookAlerts": true, "enableIntegrationAlerts": true, "enablePostRequestEscalation": false, "enableMaintenanceWindows": true, "enablePdfReports": true, "notes": null, "createdAt": "2026-02-26T12:00:00.000Z", "updatedAt": "2026-02-26T12:00:00.000Z", "usedByCustomerCount": 4 } ] ``` ## Response with `summary=1` ```bash curl -X GET "$BASE_URL/api/package-configs?summary=1" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` Every entry carries the same fields as above plus a `summary` object: ```json [ { "id": 10, "packageType": "pro", "maxUrls": 100, "maxStatusPages": null, "usedByCustomerCount": 4, "summary": { "customers": 4, "monitorsActive": 37, "capacity": 400, "statusPages": 3, "statusPageCapacity": 20 } } ] ``` - `customers`: customers assigned to this config; identical to `usedByCustomerCount`. - `monitorsActive`: all monitors of those customers that are not disabled, every type counted (website, DNS, domain, ICMP, SMTP, SSH, FTP, IMAP/POP), the same count the package limit is enforced against. - `capacity`: `customers × maxUrls`. If the config has no `maxUrls` of its own, the default of its package type is used; `0` means neither is known. - `statusPages`: all status pages of those customers, published or not, the same count the status page limit per customer is enforced against. Pages without a customer never count. - `statusPageCapacity`: `customers × maxStatusPages`, or `null` when the config has no status page limit (unlimited). ## Common errors - `400 Organization ID is required in the authenticated session` when no organization can be derived from the current session/token - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you cannot access the organization
### Create Report
URL: https://docs.uptimeify.io/api/organization/reports/create-report
Description: Creates an organization-level report configuration. Requires a plan that includes organization reports and available report quota.
Summary: `POST /api/organization/reports` Creates a recurring organization report. The organization is derived from your authenticated session or API token. Requires organization **admin** (API tokens act as organization admins). Read-only users cannot create reports. ## Request Body | Field | Type | Required | Notes | |---|---|---|---| | `name` | string | yes | 1-200 chars. | | `enabled` | boolean | no | Default `true`. | | `frequency` | `"daily" \| "weekly" \| "monthly"` | no | Default `monthly`. | | `weekday` | integer 0-6 | when `weekly` | 0 = Sunday. | | `dayOfMonth` | integer 1-28 | when `monthly` | Capped at 28. | | `sendHour` | integer 0-23 | no | Default `2`, in `timezone`. | | `timezone` | string | no | IANA tz, default `Europe/Berlin`. | | `scopeMode` | `"all" \| "customers" \| "tags"` | no | Default `all`. | | `scopeCustomerIds` | integer[] | when `customers` | Must belong to your organization. | | `scopeTagIds` | integer[] | when `tags` | Must belong to your organization. | | `inclusionMode` | `"all" \| "problems" \| "threshold"` | no | Default `all`. | | `problemSignals` | object | no | `{ incident, downtimeMinutes, sslDaysLt, responseBreach }`. | | `thresholdUptimeLt` | number | when `threshold` | e.g. `99.9`. | | `thresholdResponseGt` | integer (ms) | when `threshold` | | | `sendWhenEmpty` | boolean | no | Send an "all clear" report when no site matches. Default `false`. | | `sections` | object | no | Six booleans toggling report sections. | | `monitorTypes` | string[] | no | Which monitor types the report covers. One or more of `website`, `dns`, `dnsbl`, `domain`, `icmp`, `smtp`, `ssh`, `tcp`, `ftp`, `imap`. Default: all 10. Must contain at least one entry. | | `sectionsByType` | object | no | Per-type section toggles: `{ "": { "": boolean } }`. Legal `sectionKey`s depend on the type: see [Section keys by monitor type](#section-keys-by-monitor-type) below. Sending a section key that isn't legal for its type is rejected with `400 Bad Request`. | | `groupByCustomer` | boolean | no | Sub-group each monitor type's table by customer. Default `false`. | | `includeStatusPages` | boolean | no | Adds the status pages section at the end of the report (published state, customer, components, incidents including those routed by incident management status page rules, maintenance, subscribers). Scope `customers` lists those customers' pages; scope `tags` lists pages that show at least one monitor with one of the tags, as a component or as a monitor of the page's customer. Default `true`. | | `format` | `"email" \| "email_pdf"` | no | Default `email_pdf`. | | `recipientEmails` | string[] | no | Agency-side email recipients (max 50). | | `recipientUserIds` | string[] | no | Organization team member user ids (max 50). | ### Section keys by monitor type | Monitor type | Legal `sectionKey`s | |---|---| | `website`, `dns`, `icmp`, `smtp`, `ssh`, `tcp`, `ftp`, `imap` | `fleetSummary`, `worstPerformers`, `perMonitorTable`, `incidentLog` | | `website` (additionally) | `sslExpiry` | | `dnsbl` | `dnsblStatus` | | `domain` | `domainExpiry` | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/organization/reports" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Weekly Ops Digest", "frequency": "weekly", "weekday": 1, "scopeMode": "all", "inclusionMode": "problems", "problemSignals": { "incident": true, "downtimeMinutes": 5, "sslDaysLt": 14, "responseBreach": true }, "format": "email_pdf", "recipientEmails": ["ops@agency.io"] }' ``` ## Response ```json { "id": "3f1c9c1e-8d2a-4c7e-9b1a-2d5f6a7b8c90", "name": "Weekly Ops Digest", "enabled": true, "frequency": "weekly", "weekday": 1, "dayOfMonth": null, "sendHour": 2, "timezone": "Europe/Berlin", "scopeMode": "all", "inclusionMode": "problems", "monitorTypes": ["website", "dns", "dnsbl", "domain", "icmp", "smtp", "ssh", "tcp", "ftp", "imap"], "sectionsByType": {}, "groupByCu…
### Delete Report
URL: https://docs.uptimeify.io/api/organization/reports/delete-report
Description: Permanently deletes an organization report configuration and its scheduling. Past report runs are not deleted.
Summary: `DELETE /api/organization/reports/:id` Deletes a report configuration. `:id` is the report's `id` (a UUID). The organization is derived from your authenticated session or API token, and the report must belong to it. Requires organization **admin** (API tokens act as organization admins). Read-only users cannot delete reports. This stops future scheduled runs of the report. Historical [report runs](/api/organization/reports/list-report-runs) already generated for this report are not affected and remain retrievable. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" REPORT_ID="3f1c9c1e-8d2a-4c7e-9b1a-2d5f6a7b8c90" curl -X DELETE "$BASE_URL/api/organization/reports/$REPORT_ID" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "success": true } ``` ## Common errors - `401 Unauthorized`: not authenticated. - `403 Forbidden` (`forbidden`): not an organization admin. - `404 Not Found` (`notFound`): no report with this id exists for your organization. - `400 Invalid Report identifier`: `:id` is not shaped like a UUID. Report ids are always UUIDs; a numeric id is not accepted here.
### Download Report PDF
URL: https://docs.uptimeify.io/api/organization/reports/download-report-pdf
Description: Streams the archived PDF of a report run as the response body.
Summary: `GET /api/organization/report-runs/:id/pdf` Streams the PDF archived for a report run directly in the response body. `:id` is the run's `id` (a UUID), as returned by [List Report Runs](/api/organization/reports/list-report-runs). The run must belong to your organization. Available to any organization role, including **read-only** users. A caller restricted to some customers (customer-bound token or login) only reaches reports whose scope is `customers` and lists only customers in their scope; any other report answers `404`. The bytes are read from object storage server-side and returned to you; the object itself is never exposed as a URL, so the session/token check on this request is the entire access control for the file. Only runs with `format: "email_pdf"` that completed successfully archive a PDF. Check `hasPdf` on the run before calling this endpoint. `format: "email"` runs, and runs that failed or were skipped, have no PDF and return `404`. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" RUN_ID="9a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" curl -X GET "$BASE_URL/api/organization/report-runs/$RUN_ID/pdf" \ -H "Authorization: Bearer $TOKEN" \ -o report.pdf ``` ## Response `200 OK` with the PDF bytes as the response body. `Content-Type: application/pdf`, `Content-Disposition: attachment; filename="report-.pdf"` (`` is derived from the run's own period label, e.g. `report-08-2026.pdf`), `Cache-Control: private, max-age=300`, `X-Content-Type-Options: nosniff`. ## Common errors - `401 Unauthorized`: not authenticated. - `403 Forbidden` (`forbidden`): you do not have access to this organization. - `404 Not Found` (`reportRunNotFound`): no run with this id exists for your organization. - `404 Not Found` (`reportRunNoPdf`): the run has no archived PDF (it was an email-only report, or generation failed/was skipped). - `404 Not Found` (`reportPdfNotFound`): the run record has a PDF path, but the object could not be read from object storage. - `400 Invalid Report run identifier`: `:id` is not shaped like a UUID. Run ids are always UUIDs; a numeric id is not accepted here.
### Get Report
URL: https://docs.uptimeify.io/api/organization/reports/get-report
Description: Returns a single organization report configuration by its public id.
Summary: `GET /api/organization/reports/:id` Returns one report configuration. `:id` is the report's `id` (a UUID), as returned by [Create Report](/api/organization/reports/create-report) or [List Reports](/api/organization/reports/list-reports). The report must belong to your organization. Available to any organization role, including **read-only** users. A caller restricted to some customers (customer-bound token or login) only reaches reports whose scope is `customers` and lists only customers in their scope; any other report answers `404`. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" REPORT_ID="3f1c9c1e-8d2a-4c7e-9b1a-2d5f6a7b8c90" curl -X GET "$BASE_URL/api/organization/reports/$REPORT_ID" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "id": "3f1c9c1e-8d2a-4c7e-9b1a-2d5f6a7b8c90", "name": "Weekly Ops Digest", "enabled": true, "frequency": "weekly", "weekday": 1, "dayOfMonth": null, "sendHour": 2, "timezone": "Europe/Berlin", "scopeMode": "all", "scopeCustomerIds": [], "scopeTagIds": [], "inclusionMode": "problems", "problemSignals": { "incident": true, "downtimeMinutes": 5, "sslDaysLt": 14, "responseBreach": true }, "thresholdUptimeLt": null, "thresholdResponseGt": null, "sendWhenEmpty": false, "sections": { "fleetSummary": true, "worstPerformers": true, "perSiteTable": true, "incidentLog": true, "sslExpiry": true, "groupByCustomer": false }, "monitorTypes": ["website", "dns", "dnsbl", "domain", "icmp", "smtp", "ssh", "tcp", "ftp", "imap"], "sectionsByType": {}, "groupByCustomer": false, "includeStatusPages": true, "format": "email_pdf", "recipientEmails": ["ops@agency.io"], "recipientUserIds": [], "createdAt": "2026-06-01T02:00:00.000Z", "updatedAt": "2026-06-01T02:00:00.000Z" } ``` ## Common errors - `401 Unauthorized`: not authenticated. - `403 Forbidden` (`forbidden`): you do not have access to this organization. - `404 Not Found` (`notFound`): no report with this id exists for your organization. - `400 Invalid Report identifier`: `:id` is not shaped like a UUID. Report ids are always UUIDs; a numeric id is not accepted here.
### List Report Runs
URL: https://docs.uptimeify.io/api/organization/reports/list-report-runs
Description: Returns the organization's report generation/delivery history, optionally filtered to a single report.
Summary: `GET /api/organization/report-runs` Lists report runs for the organization, newest first. A run is created every time a report is generated: on schedule or via [Send Report Now](/api/organization/reports/send-report-now). The organization is derived from your authenticated session or API token. Available to any organization role, including **read-only** users. A caller restricted to some customers (customer-bound token or login) only sees reports whose scope is `customers` and lists only customers in their scope; reports over all customers or over tags are left out. ## Query Parameters | Field | Type | Required | Notes | |---|---|---|---| | `reportId` | string (uuid) | no | Restrict to runs of one report. If the id does not resolve to a report in your organization, the list is empty. | | `limit` | integer | no | Default `50`, capped at `200`. | | `offset` | integer | no | Default `0`. | | `envelope` | string | no | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/organization/report-runs?reportId=3f1c9c1e-8d2a-4c7e-9b1a-2d5f6a7b8c90&limit=20&envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "items": [ { "id": "9a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "reportId": "3f1c9c1e-8d2a-4c7e-9b1a-2d5f6a7b8c90", "reportName": "Weekly Ops Digest", "periodStart": "2026-05-25T00:00:00.000Z", "periodEnd": "2026-06-01T00:00:00.000Z", "periodLabel": "May 25 - Jun 1, 2026", "status": "sent", "trigger": "schedule", "sentAt": "2026-06-01T02:00:12.000Z", "recipients": ["ops@agency.io"], "hasPdf": true, "summary": { "sitesIncluded": 42, "incidents": 3 }, "createdAt": "2026-06-01T02:00:00.000Z" } ], "total": 1, "page": 1, "perPage": 20 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form (a bare array of the same items), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. `status` is one of `pending`, `generating`, `sent`, `failed`, `skipped_empty`. `trigger` is `schedule` or `manual`. `hasPdf` is `true` only when a PDF was archived for this run. Use it to decide whether to call [Download Report PDF](/api/organization/reports/download-report-pdf). ## Common errors - `401 Unauthorized`: not authenticated. - `403 Forbidden` (`forbidden`): you do not have access to this organization. - `400 Invalid Report identifier`: the `reportId` query parameter was sent but is not shaped like a UUID. A well-formed `reportId` that matches no report returns an empty list instead.
### List Reports
URL: https://docs.uptimeify.io/api/organization/reports/list-reports
Description: Returns all organization report configurations.
Summary: `GET /api/organization/reports` Lists the organization's recurring report configurations, newest first. The organization is derived from your authenticated session or API token. Available to any organization role, including **read-only** users. A caller restricted to some customers (customer-bound token or login) only sees reports whose scope is `customers` and lists only customers in their scope; reports over all customers or over tags are left out. ## Query Parameters | Parameter | Type | Default | Description | |---|---|---|---| | `envelope` | string | none | `items`: answer as `{ items, total, page, perPage }`. Becomes the default on 2027-01-18. | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X GET "$BASE_URL/api/organization/reports?envelope=items" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response ```json { "items": [ { "id": "3f1c9c1e-8d2a-4c7e-9b1a-2d5f6a7b8c90", "name": "Weekly Ops Digest", "enabled": true, "frequency": "weekly", "weekday": 1, "dayOfMonth": null, "sendHour": 2, "timezone": "Europe/Berlin", "scopeMode": "all", "scopeCustomerIds": [], "scopeTagIds": [], "inclusionMode": "problems", "problemSignals": { "incident": true, "downtimeMinutes": 5, "sslDaysLt": 14, "responseBreach": true }, "thresholdUptimeLt": null, "thresholdResponseGt": null, "sendWhenEmpty": false, "sections": { "fleetSummary": true, "worstPerformers": true, "perSiteTable": true, "incidentLog": true, "sslExpiry": true, "groupByCustomer": false }, "monitorTypes": ["website", "dns", "dnsbl", "domain", "icmp", "smtp", "ssh", "tcp", "ftp", "imap"], "sectionsByType": {}, "groupByCustomer": false, "includeStatusPages": true, "format": "email_pdf", "recipientEmails": ["ops@agency.io"], "recipientUserIds": [], "createdAt": "2026-06-01T02:00:00.000Z", "updatedAt": "2026-06-01T02:00:00.000Z" } ], "total": 1, "page": 1, "perPage": 1 } ``` **List form:** with `envelope=items` the list arrives as `{ items, total, page, perPage }`. Without it the endpoint still answers the current form (`{ "reports": [...] }`), which is deprecated; `{ items, ... }` becomes the default on 2027-01-18. ## Common errors - `401 Unauthorized`: not authenticated. - `403 Forbidden` (`forbidden`): you do not have access to this organization.
### Send Report Now
URL: https://docs.uptimeify.io/api/organization/reports/send-report-now
Description: Queues an immediate, out-of-schedule generation and delivery of an organization report.
Summary: `POST /api/organization/reports/:id/send-now` Enqueues a manual run of a report configuration, independent of its `frequency`/`sendHour` schedule. `:id` is the report's `id` (a UUID). The organization is derived from your authenticated session or API token, and the report must belong to it. Requires organization **admin** (API tokens act as organization admins). Read-only users cannot trigger sends. A manual send also runs when the report is switched off (`enabled: false`) and records a run; the switch only governs the schedule. This endpoint only queues the job. It does not wait for generation or delivery to complete. Poll [List Report Runs](/api/organization/reports/list-report-runs) (filtered by `reportId`) to see the resulting run once its `status` moves past `pending`. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" REPORT_ID="3f1c9c1e-8d2a-4c7e-9b1a-2d5f6a7b8c90" curl -X POST "$BASE_URL/api/organization/reports/$REPORT_ID/send-now" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "queued": true, "jobId": "orgreport-manual-3f1c9c1e-8d2a-4c7e-9b1a-2d5f6a7b8c90-1b6e..." } ``` ## Common errors - `401 Unauthorized`: not authenticated. - `403 Forbidden` (`forbidden`): not an organization admin. - `404 Not Found` (`notFound`): no report with this id exists for your organization. - `400 Invalid Report identifier`: `:id` is not shaped like a UUID. Report ids are always UUIDs; a numeric id is not accepted here.
### Update Report
URL: https://docs.uptimeify.io/api/organization/reports/update-report
Description: Updates an organization report configuration. All fields are optional; at least one must be provided.
Summary: `PATCH /api/organization/reports/:id` Partially updates a report configuration. `:id` is the report's `id` (a UUID). The organization is derived from your authenticated session or API token, and the report must belong to it. Requires organization **admin** (API tokens act as organization admins). Read-only users cannot update reports. Only send the fields you want to change. Cross-field validation (schedule and scope) is re-run against the **merged** result. A `PATCH` that only changes `frequency` to `weekly` without also sending `weekday` fails if the existing report has no `weekday` set. ## Request Body Same fields as [Create Report](/api/organization/reports/create-report), all optional, but at least one field must be present: | Field | Type | Notes | |---|---|---| | `name` | string | 1-200 chars. | | `enabled` | boolean | | | `frequency` | `"daily" \| "weekly" \| "monthly"` | | | `weekday` | integer 0-6 \| null | Required (effectively) when the resulting `frequency` is `weekly`. | | `dayOfMonth` | integer 1-28 \| null | Required (effectively) when the resulting `frequency` is `monthly`. | | `sendHour` | integer 0-23 | | | `timezone` | string | IANA tz. | | `scopeMode` | `"all" \| "customers" \| "tags"` | | | `scopeCustomerIds` | integer[] | Must belong to your organization. | | `scopeTagIds` | integer[] | Must belong to your organization. | | `inclusionMode` | `"all" \| "problems" \| "threshold"` | | | `problemSignals` | object | `{ incident, downtimeMinutes, sslDaysLt, responseBreach }`. | | `thresholdUptimeLt` | number \| null | | | `thresholdResponseGt` | integer (ms) \| null | | | `sendWhenEmpty` | boolean | | | `sections` | object | Six booleans toggling report sections. | | `monitorTypes` | string[] | One or more of `website`, `dns`, `dnsbl`, `domain`, `icmp`, `smtp`, `ssh`, `tcp`, `ftp`, `imap`. Cannot be sent as an empty array. | | `sectionsByType` | object | Per-type section toggles: `{ "": { "": boolean } }`. Legal `sectionKey`s depend on the type: see [Section keys by monitor type](/api/organization/reports/create-report#section-keys-by-monitor-type). Sending a section key that isn't legal for its type is rejected with `400 Bad Request`. | | `groupByCustomer` | boolean | Sub-group each monitor type's table by customer. | | `includeStatusPages` | boolean | Adds the status pages section at the end of the report (published state, customer, components, incidents including those routed by incident management status page rules, maintenance, subscribers). Scope `customers` lists those customers' pages; scope `tags` lists pages that show at least one monitor with one of the tags, as a component or as a monitor of the page's customer. | | `format` | `"email" \| "email_pdf"` | | | `recipientEmails` | string[] | Max 50. | | `recipientUserIds` | string[] | Max 50. | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" REPORT_ID="3f1c9c1e-8d2a-4c7e-9b1a-2d5f6a7b8c90" curl -X PATCH "$BASE_URL/api/organization/reports/$REPORT_ID" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "enabled": false, "recipientEmails": ["ops@agency.io", "cs@agency.io"] }' ``` ## Response ```json { "id": "3f1c9c1e-8d2a-4c7e-9b1a-2d5f6a7b8c90", "name": "Weekly Ops Digest", "enabled": false, "frequency": "weekly", "weekday": 1, "dayOfMonth": null, "sendHour": 2, "timezone": "Europe/Berlin", "scopeMode": "all", "inclusionMode": "problems", "monitorTypes": ["website", "dns", "dnsbl", "domain", "icmp", "smtp", "ssh", "tcp", "ftp", "imap"], "sectionsByType": {}, "groupByCustomer": false, "includeStatusPages": true, "format": "email_pdf", "recipientEmails": ["ops@agency.io", "cs@agency.io"], "recipientUserIds": [] } ``` ## Common errors - `401 Unauthorized`: not authenticated. - `403 Forbidden` (`forbidden`): not an organization admin. - `404 Not Found` (`notFound`): no report with this id exists for your organization. - `400` (`invalidReportSchedule`): the resulting `w…
### Request Data Export
URL: https://docs.uptimeify.io/api/organization/request-data-export
Description: Queues a complete export of your organization's content as JSON and CSV, delivered as a downloadable ZIP and announced by email.
Summary: `POST /api/organization/data-export` Starts a full export of everything your organization holds in Uptimeify: customers, monitors of every type, incidents and incident updates, maintenance windows, notification channels, tags, status pages, reports and their run history, billing records, team members, API token metadata, incident-management configuration and history, and (unless you opt out) the raw check history behind your monitors. The request returns immediately with `202 Accepted`. The bundle is built in the background; when it is ready, an email with a download link goes to the recipients, and the export appears as `ready` in `GET /api/organization/data-export`. ## Request body | Field | Type | Default | Description | | --- | --- | --- | --- | | `includeCheckHistory` | boolean | `true` | Include raw per-check rows. This is the bulk of the bundle; set `false` for a configuration-only export. | | `recipientEmails` | string[] | administrators of the organization | Who receives the "export is ready" email. Every address must belong to a member of this organization. Max 20. | ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/organization/data-export" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "includeCheckHistory": true }' ``` ## Response ```json { "id": "0f0f2f6a-2b3b-4a2f-9a7c-3e5f8c1d2b44", "status": "queued", "format": "json_csv", "includeCheckHistory": true, "recipientEmails": ["admin@youragency.com"], "sizeBytes": null, "retentionCutoff": null, "expiresAt": null, "downloadCount": 0, "lastDownloadedAt": null, "errorMessage": null, "manifest": null, "createdAt": "2026-07-30T09:12:44.101Z", "startedAt": null, "completedAt": null } ``` **Deprecated field:** `error` is still sent next to `errorMessage` until it is removed on 2027-01-18. Read `errorMessage`. ## What the bundle contains A ZIP with both formats plus an index: - `manifest.json`, every section with its row count, the retention cutoff per package, and completeness flags - `README.txt`, what is included, what is redacted, what is incomplete - `json/.json`, full-fidelity records - `csv/.csv`, the same records, flat and spreadsheet-ready Three rules bound the contents: - **Retention.** Time-series data (check history, alert deliveries, SMS log) reaches back as far as the data retention of the packages your customers are on. Older rows are not withheld, they no longer exist. - **Credentials.** Passwords, webhook secrets, integration and ingest tokens, API token hashes and SMTP passwords are replaced with `[redacted]`. Custom headers (`headers`, `webhookHeaders`, `customHeaders`) keep their names, every value is replaced with `[redacted]`. The surrounding record is exported in full. - **Audit log.** `organization/audit-log` holds administrative actions and sign-in events of the last 12 months: who did what; for sign-ins and connected apps also from which IP and user agent. Older entries no longer exist. Its `note` in `manifest.json` states the window. For one period as a CSV file use [Export Audit Log](/api/organization/export-audit-log). Raw check history is capped per monitor type (100,000 newest rows by default). A capped section is flagged with `truncated` in `manifest.json`; pull the remainder per monitor via `GET /api/websites/{id}/check-history?format=csv` and the equivalent endpoints of the other monitor types. `truncated` also marks a section whose source could not be read while the export ran. Such a section carries a `note` beginning with `INCOMPLETE` and zero rows, which is not a claim that the section is empty. Request a new export to retry. ## Rate limits - One export at a time per organization (`409 exportAlreadyRunning`). - One request per organization every 6 hours (`429 exportCooldown`). - A finished export stays downloadable for 7 days, then the file is deleted and the record flips to `expired`. ## Common errors - `400 User must belon…
### Update Billing Details
URL: https://docs.uptimeify.io/api/organization/update-billing-details
Description: Updates billing information for the organization in your authenticated session.
Summary: `PATCH /api/organization/billing` ## Request Body ```json { "billingEmail": "billing@deinkunde.com" } ``` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PATCH "$BASE_URL/api/organization/billing" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "billingEmail": "billing@deinkunde.com" }' ``` ## Notes - `billingEmail` is currently the only supported field for this endpoint. - The organization is derived automatically from your authenticated session or API token. - The legacy route `PATCH /api/organizations/:organizationPublicId/billing` remains supported for compatibility. - The plural org-less alias `PATCH /api/organizations/billing` is also supported. - Global admins need an active organization context in the authenticated session for the org-less route. ## Common errors - `400 Invalid request body` when the payload does not match the schema - `400 Organization ID is required in the authenticated session` when no organization can be derived from the current session/token - `401 Unauthorized` when you are not logged in - `403 Forbidden` when you do not have admin access to update billing settings ## Response Returns the updated organization billing details. See [Error Codes](/api/error-codes-and-known-pitfalls) for error responses.
### Update Organization
URL: https://docs.uptimeify.io/api/organization/update-organization
Description: Updates the organization from your authenticated session.
Summary: `PATCH /api/organization` ## Request Body ```json { "name": "New Name", "companyName": "New Company Name", "street": "New Street", "postalCode": "54321", "city": "New City", "country": "US", "vatId": "US123", "countryCode": "AT", "billingEmail": "new@deinkunde.com", "contractEmail": "contracts@deinkunde.com", "requireMfaAdmins": true, "requireMfaEditors": false, "requireMfaReadonly": false, "requireMfaCustomers": false, "defaultNotificationChannels": { "email": true, "sms": false, "webhook": true, "integrations": false }, "defaultNotificationTargets": { "email": "both", // customer, organization, both "sms": "organization", "webhook": "organization", "integrations": "customer" } } ``` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PATCH "$BASE_URL/api/organization" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "name": "New Name", "billingEmail": "new@deinkunde.com" }' ``` Notes: - The organization is derived automatically from your authenticated session or API token. - The legacy route `PATCH /api/organizations/:organizationPublicId` remains supported for compatibility. - The plural org-less alias `PATCH /api/organizations` is also supported. - Global admins need an active organization context in the authenticated session for the org-less route. - `contractEmail` (e-mail address or `null`) receives notices of changes to the terms, the DPA and the privacy policy. When it is set, only this address receives them and no admin does; `null` sends them to every admin of the organization again. - `countryCode` is the organization's billing country as an ISO-3166-1 alpha-2 code (two letters, case-insensitive on input, always stored and returned uppercased). It determines VAT treatment: reverse charge under AGB § 10.2 requires this to be an EU member state other than Germany. - Writing `vatId` or `countryCode` (either one, in the same request or separately) resets `vatIdStatus` to `unverified`. A previous `valid` verdict never survives an edit to either field, re-validate with [Validate VAT ID](/api/organization/validate-vat-id) after the change to restore reverse-charge eligibility. - **Quota changes are not symmetric.** A change whose `quotaMonthlyPriceCents` is **higher** than the organization's current one takes effect immediately, and the difference is charged pro rata for the rest of the current billing period. A change whose price is **lower** does **not** take effect immediately: by default it is scheduled for the end of the current billing period, and no credit is issued for the unused part of the higher plan (see `quotaChangeEffective` below to apply it immediately instead). This applies from 1 January 2027; until 31 December 2026 a reduction on a monthly plan takes effect immediately with a pro-rata credit by default. Until it fires, the organization keeps its current plan and every quota field on the organization still describes that plan. Direction is decided by price alone, never by the monitor limit, so a tier that costs less for *more* monitors is still a reduction. - A scheduled reduction is returned as `pendingQuotaChange` on both this endpoint and [Get Organization Details](/api/organization/get-organization-details); it is `null` when nothing is scheduled. There is at most one scheduled change per organization: a second reduction replaces the first, and an increase supersedes it (otherwise you would be silently dropped back at the period boundary). To call one off without changing plan, use [Cancel Scheduled Quota Change](/api/organization/cancel-pending-quota-change), re-sending the current tier here counts as unchanged and will not do it. - **Per-day billing from billing month January 2027.** Every calendar day in Europe/Berlin costs the monthly price of the plan in effect on that day, divided by the number of days in that month (28 to 31); a full month costs exactly the monthly price. A plan change appli…
### Upsert Package Config
URL: https://docs.uptimeify.io/api/organization/upsert-package-config
Description: Creates a new package config (by :packageType) or updates an existing one. packageType is a free-form identifier chosen by the organization, and customer endpoints can later reference that same key.
Summary: `PATCH /api/package-configs/:packageType` This endpoint is the source of truth for alerting-related defaults like `alertConsecutiveChecks` and feature flags like `enableEmailAlerts`. The alert flags (`enableEmailAlerts`, `enableSmsAlerts`, `enableWebhookAlerts`, `enableIntegrationAlerts`) decide only which of your organization's own channels alert about customers of this package. Channels a customer sets up themselves always reach that customer. A customer's own `enable*Alerts` value, when set, replaces the package for that customer. ## Request Body All fields are optional and can be updated over time. If you want a human-friendly package label in the UI, set `displayName` in addition to the technical `packageType` key. ```json { "displayName": "Pro Care", "maxUrls": 100, "maxStatusPages": 5, "dataRetentionMonths": 12, "checkIntervalMinutes": 1, "checkLocations": 3, "notificationDelayMinutes": 0, "reminderDelayMinutes": 10, "alertConsecutiveChecks": 3, "alertLocationThreshold": "majority", "alertLocationThresholdCount": 2, "alertReminderInterval": 60, "enableEmailAlerts": true, "enableSmsAlerts": true, "enableWebhookAlerts": true, "enableIntegrationAlerts": true, "enablePostRequestEscalation": false, "enableMaintenanceWindows": true, "enablePdfReports": true, "monthlyReportsDefault": true, "allowSelfService": true, "maxSelfServiceUrls": 10, "notes": "Default for PRO customers" } ``` `notes` (text up to 4096 characters, or `null`) is a free internal note. Leaving it out keeps the current note; `null` or an empty string clears it. ### Monitor ownership defaults `allowSelfService` (default `false`) and `maxSelfServiceUrls` (default `0`) are the package-tier defaults for the [managed vs. self-service](/monitoring/managed-vs-self-service) model. Every customer on the package inherits them unless the customer carries its own non-`null` override (see [Update Customer](/api/customers/update-customer)). `maxSelfServiceUrls` caps a customer's **total** self-service monitors across all monitor types. The `enable*` alert flags double as the inherited channel-type policy for the same model. ### Status pages per customer `maxStatusPages` (integer or `null`, default `null` = unlimited) caps how many status pages one customer of this package may have. Creating one more page for such a customer, or moving a page to them, answers `409` with `data.code: statusPageLimitReached` and the limit in `data.max`. Pages without a customer never count, and an organization has no limit of its own. Send `null` to remove the limit. ### `alertConsecutiveChecks` An integer between **1 and 10** (values outside that range are rejected with `400` and `data.code` `invalidRequestBody`). It is the number of locations that must see a failure before an incident opens, the failing location included. When a check fails, the next locations re-check within seconds: `1` opens the incident on the first failure without confirmation, `2` waits for one more location to confirm, and so on. New packages default to **2** (before 30.10.2026 the default was 1; existing values are unchanged). The value also bounds how many successful cycles are required before an incident closes. A very large value therefore does not just delay alerting, it delays recovery: at a 5-minute cadence a value of 999 would keep an incident open for 83 hours of uninterrupted green checks. The cap matches the one the dashboard has always enforced. ### `monthlyReportsDefault` `monthlyReportsDefault` (boolean, default `true`) is a **template**, not a live switch: it seeds a new customer's `monthlyReportsEnabled` at creation time. It never rewrites an existing customer, whose own value always wins once set. To push a changed default onto customers **already** on this package, call [Apply Report Default](/api/organization/apply-report-default) afterwards. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X PATCH "$BASE_URL/api/package-configs/pro" \ -H "Authorization: Beare…
### Validate VAT ID
URL: https://docs.uptimeify.io/api/organization/validate-vat-id
Description: Validates the organization's stored VAT identification number against the EU VIES register and persists the verdict. Only a valid VAT ID from another EU member state qualifies the organization for reverse-charge invoicing under AGB § 10.2.
Summary: `POST /api/organizations/:organizationPublicId/vat-id/validate` ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" ORG_ID="" curl -X POST "$BASE_URL/api/organizations/$ORG_ID/vat-id/validate" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` Notes: - This endpoint takes no request body. It validates whatever `vatId` and `countryCode` are currently stored on the organization, set them first with [Update Organization](/api/organization/update-organization) if needed. - Validation is a deliberate, explicit action, not a side effect of saving the organization. The EU VIES service is slow and occasionally unavailable per member state, so a `PATCH` to the organization must not fail or hang on it. Saving a new `vatId` or `countryCode` resets `vatIdStatus` to `unverified`; calling this endpoint is what turns it back into a verdict. - Reverse charge under AGB § 10.2 applies only when the organization's country is an EU member state other than Germany, a VAT ID is stored, and `vatIdStatus` is exactly `valid`. Every other combination bills at the standard rate. - Requires organization write access (organization admin or global admin) from an unrestricted session or token, the same authorization as [Update Organization](/api/organization/update-organization). A customer-scoped API token cannot call this endpoint, even with `admin`-level role. ## Response ```json { "vatIdStatus": "valid", "vatIdValidatedAt": "2026-07-30T09:15:00.000Z", "vatIdValidationNote": null, "taxTreatment": "reverse_charge" } ``` `vatIdStatus` is one of: | Value | Meaning | | --- | --- | | `unverified` | Not yet validated, or the stored `vatId`/`countryCode` changed since the last validation (see above). Never returned by this endpoint, it is the pre-validation default. | | `valid` | VIES confirmed the VAT ID. The only status that grants reverse charge. | | `invalid` | VIES rejected the VAT ID, its country prefix does not belong to an EU VAT country, or it does not match the organization's stored `countryCode`. | | `unavailable` | VIES could not give a verdict, a timeout, an HTTP error, or a member state's registry reporting itself down (`MS_UNAVAILABLE`). Deliberately distinct from `invalid`: an outage must never be read as "the VAT ID is wrong," since that would strip a legitimate customer of reverse charge. Retry later. | `taxTreatment` reflects the resulting billing treatment and is one of `standard` or `reverse_charge`. `vatIdValidationNote` is a short, human-readable reason (e.g. why a check came back `invalid` or `unavailable`); `null` on a `valid` result. ## Common errors - `401 Unauthorized` (`data.code: unauthorized`) when you are not logged in - `400 Invalid Organization identifier` when `:organizationPublicId` is neither a legacy integer id nor a valid UUID public identifier - `403 Forbidden` (`data.code: forbidden`) when you do not have write access to the organization - `403 Forbidden` (`data.code: customerScopedTokenForbidden`) when called with a customer-scoped API token; this is an organization-wide action and requires an organization-scoped token or a session - `404 Organization not found` (no `data.code`) when `:organizationPublicId` does not resolve to an existing organization - `404 Organization not found` (`data.code: organizationNotFound`) when the organization is deleted in the narrow window between resolving `:organizationPublicId` and the endpoint's own lookup, a race, not the typical not-found response - `422 No VAT ID stored for this organization` (`data.code: vatIdMissing`) when the organization has no `vatId` set, store one first with [Update Organization](/api/organization/update-organization) - `409 The VAT ID or country changed while validation was in flight` (`data.code: vatIdChangedDuringValidation`) when `vatId` or `countryCode` was edited concurrently while VIES was being queried, the in-flight verdict is discarded rather than written to stale data. Safe…
### Service Status
URL: https://docs.uptimeify.io/api/service-status
Description: Public, unauthenticated endpoint that returns Uptimeify's own platform availability, check and alert delivery percentages, component states, and the hash-chained frozen monthly totals.
Summary: `GET /api/service-status` No authentication required. Returns no customer data, only the platform's own delivery figures, published component states, and the frozen monthly totals behind them. ## Example (cURL) ```bash curl -X GET "https://uptimeify.io/api/service-status" \ -H "Accept: application/json" ``` ## Response ```json { "checkDelivery": { "pct": 99.97, "coveragePct": 99.94, "announcedMaintenanceMinutes": 0, "insufficientData": false, "windowDays": 90 }, "alertDelivery": { "pct": 97.31, "sampleSize": 2454, "endpointFailures": 140, "latencyP90Ms": 1727, "latencySampleSize": 812, "insufficientData": false, "latencyInsufficientData": false }, "components": [ { "key": "de-fra", "displayName": "Frankfurt (DE)", "state": "operational", "coveragePct": 99.94 }, { "key": "alerting", "displayName": "Alert Delivery", "state": "operational", "coveragePct": 100 } ], "frozenMonths": [ { "month": "2026-06-01", "sliKind": "check_delivery", "scopeKey": "mesh", "numerator": 4318204, "denominator": 4319850, "unknownUnits": 612, "rowHash": "9f2c1a7e4b8d0f3a6c5e2b1d8a7f4e9c0b3d6a1f8e5c2b9d7a4f1e8c5b2d9a6f" }, { "month": "2026-06-01", "sliKind": "measurement_coverage", "scopeKey": "mesh", "numerator": 43176, "denominator": 43200, "unknownUnits": 24, "rowHash": "4d1b8e0cc0a2f7593e6b4c1d8a05f2e7b9c3d6a1f8e5c2b9d7a4f1e8c5b2d9a6" } ] } ``` Notes: - `checkDelivery.pct` and `alertDelivery.pct` are trailing `windowDays` figures (currently 90 days), truncated to two decimals, never rounded up. - **`checkDelivery.pct` counts scheduled CYCLES, not checks.** Every monitor is due one check per check interval, and that is one cycle. A cycle counts as delivered if at least one check row exists for that monitor, from **any** of our locations, inside its minute plus a two-minute tolerance; a cycle that produced no check anywhere is the only thing that lowers the figure. The `numerator` and `denominator` of a `check_delivery` row are therefore whole cycle counts, fulfilled over due. **Which location ran a given cycle is not part of this figure.** The scheduler visits one rotating location per cycle rather than all of them at once, so a location that has not come round yet has not failed at anything, and pricing its share as a shortfall reported outages that had not happened. Losing a location appears in `components[]` instead, per component, with its own `coveragePct`. - **`unknownUnits` is NOT in the denominator of any percentage on this endpoint.** A percentage is measured over what the platform could actually account for; `denominator` is the expectation over the recorded units and `unknownUnits` is the expectation over the units that were never recorded, a gap in the per-minute recorder, a stalled rollup. The two are separate axes because "we were unavailable" and "we could not measure" are different facts: folding the second into the first would publish an outage that did not happen and make the figure a measure of the recorder's own reliability. - **`coveragePct` is the second half of every claim and is never omitted.** It is the share of the window the platform can account for, `0`-`100`, truncated to two decimals; `null` only when nothing was owed in the window yet. `checkDelivery.coveragePct` covers the whole mesh; `components[].coveragePct` is per component and is `null` for a component that has never been measured at all. For the conservative reading (the share of the window positively confirmed as delivered), multiply the two: `pct x coveragePct / 100`. - **`checkDelivery.announcedMaintenanceMinutes` is announced platform maintenance, taken out of both figures.** Minutes inside a maintenance we announced to customers in advance count neither as delivered nor as a measurement gap: they are excluded from `pct` and from `coveragePct` alike, and published here as a count of minutes over the window instead, so the exclusion is visible rather than silent. `0` when the window holds none. - From any `frozenMonths` row you can recompute coverage yourself…
### Status Pages
URL: https://docs.uptimeify.io/api/status-pages
Description: Create and manage public status pages that display the operational status of your monitored websites, recent incidents, and maintenance windows.
Summary: Status pages can be public (accessible by anyone) or restricted to customer members. Custom domains are supported with DNS verification. ## Authentication All examples assume a bearer token: ```bash BASE_URL="https://uptimeify.io" TOKEN="" ``` ## Endpoints - [List Status Pages](/api/status-pages/list-status-pages) - [Create Status Page](/api/status-pages/create-status-page) - [Update Status Page](/api/status-pages/update-status-page) - [Delete Status Page](/api/status-pages/delete-status-page) - [Get Public Status Page](/api/status-pages/get-public-status-page) - [Get Status Page](/api/status-pages/get-status-page) - [Get Status Page Design](/api/status-pages/get-status-page-design) - [Update Status Page Design](/api/status-pages/update-status-page-design) - [List Status Page Subscribers](/api/status-pages/list-subscribers) - [Delete Status Page Subscriber](/api/status-pages/delete-subscriber) - [Export Status Page Subscribers](/api/status-pages/export-subscribers) - [Add Custom Domain](/api/status-pages/add-status-page-domain) - [Get Status Page Domain](/api/status-pages/get-status-page-domain) - [Status Page Domain Diagnostics](/api/status-pages/get-status-page-domain-diagnostics) - [Remove Custom Domain](/api/status-pages/remove-status-page-domain) - [Verify Status Page Domain](/api/status-pages/verify-status-page-domain) - [Activate Status Page Domain](/api/status-pages/activate-status-page-domain) - [Get Status Page Module](/api/status-pages/get-status-page-module) - [Activate Status Page Module](/api/status-pages/activate-status-page-module) - [List Status Page Components](/api/status-pages/list-status-page-components) - [Create Status Page Component](/api/status-pages/create-status-page-component) - [Update Status Page Component](/api/status-pages/update-status-page-component) - [Delete Status Page Component](/api/status-pages/delete-status-page-component) - [Reorder Status Page Components](/api/status-pages/reorder-status-page-components) - [List Status Page Component Groups](/api/status-pages/list-status-page-component-groups) - [Create Status Page Component Group](/api/status-pages/create-status-page-component-group) - [Update Status Page Component Group](/api/status-pages/update-status-page-component-group) - [Delete Status Page Component Group](/api/status-pages/delete-status-page-component-group) - [List Status Page Maintenance](/api/status-pages/list-status-page-maintenance) - [Schedule Status Page Maintenance](/api/status-pages/create-status-page-maintenance) - [Get Status Page Maintenance](/api/status-pages/get-status-page-maintenance) - [Update Status Page Maintenance](/api/status-pages/update-status-page-maintenance) - [Delete Status Page Maintenance](/api/status-pages/delete-status-page-maintenance) - [Cancel Status Page Maintenance](/api/status-pages/cancel-status-page-maintenance) - [Complete Status Page Maintenance](/api/status-pages/complete-status-page-maintenance) - [Post Status Page Maintenance Update](/api/status-pages/post-status-page-maintenance-update) - [List Status Page Templates](/api/status-pages/list-status-page-templates) - [Create Status Page Template](/api/status-pages/create-status-page-template) - [Get Status Page Template](/api/status-pages/get-status-page-template) - [Update Status Page Template](/api/status-pages/update-status-page-template) - [Delete Status Page Template](/api/status-pages/delete-status-page-template) ## Customer, components and groups A status page belongs either to one customer (`customerId`) or, without a customer (`customerId: null`), to the whole organization. Only organization-wide roles and API tokens see and manage a page without a customer: customer-scoped users and tokens do not get it in lists and are answered `403` on its component and group endpoints. What a page shows: - **Components**: explicit rows, each either a monitor (`sourceKind: monitor`) or a manually maintained entry (`sourceKind: manual`), optionally bundled in groups. - **Cus…
### Activate Status Page Domain
URL: https://docs.uptimeify.io/api/status-pages/activate-status-page-domain
Description: Activates a verified custom domain for a status page. Organization-wide: admin only; customer-bound: by the page's ownership class.
Summary: `POST /api/status-pages/domains/activate` **Access:** organization-wide callers need the role `admin` (an organization-wide `editor` or `readonly` gets `403 forbidden`). Customer-bound users (also with the role `readonly`) and customer-bound API tokens follow the ownership class of the page the domain is bound to: allowed on `self_service` pages, on `managed` pages only with the customer's `canEditManaged` exception, otherwise `403` with `data.code: managed_by_organization`. A domain bound to no status page does not exist for a customer-bound caller: `404` (`domainNotFound`). ## Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `domainId` | number | Yes | - | The verified domain ID to activate | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/status-pages/domains/activate" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "domainId": 42 }' ``` ## Response ```json { "activated": true, "domain": { "id": 42, "hostname": "status.deinkunde.com", "status": "active", "role": "status_page", "isPrimary": false, "verificationToken": "abc123-def456-ghi789", "verifiedAt": "2026-05-01T12:00:00.000Z", "lastVerificationError": null, "lastVerificationErrorAt": null, "createdAt": "2026-05-01T11:00:00.000Z", "updatedAt": "2026-05-01T12:30:00.000Z" } } ``` ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` when you are an organization-wide caller without the role admin - `403 Forbidden` (`managed_by_organization`) when you are customer-bound (user, also with the role `readonly`, or token) and the page is `managed` without the customer's `canEditManaged` exception - `404 Not Found` (`domainNotFound`) when you are customer-bound and the domain is bound to no status page - `400 Bad Request` when the domain is not yet verified - `409 Conflict` (`domainAlreadyClaimed`) when another organization holds this hostname as verified or active meanwhile. The owner is not disclosed.
### Activate Status Page Module
URL: https://docs.uptimeify.io/api/status-pages/activate-status-page-module
Description: Turns the status pages module on for your organization. Idempotent.
Summary: `POST /api/status-pages/module/activate` The only way to switch the status pages module on. No request body. Calling it again on an organization where the module is already on changes nothing and answers `alreadyEnabled: true`. The activation is written to the organization's audit log. There is no endpoint to switch the module off. ## Suspended organizations Status pages are free and stay available when billing locks an account. An organization suspended for billing reasons (trial ended, trial or subscription cancelled, unpaid invoice) may still call this endpoint. It switches the module on and returns the organization to `active` as a status-pages-only organization: status pages, custom domains and subscriber notifications run, monitoring and incident management stay paused, and the scheduled data deletion is cancelled. Booking a plan again restores monitoring. An organization suspended by Uptimeify support stays locked and gets `423`. ## Access Organization `admin` only. Customer-scoped API tokens are rejected. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/status-pages/module/activate" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" ``` ## Response `200 OK` ```json { "enabled": true, "activatedAt": "2026-10-27T09:00:00.000Z", "alreadyEnabled": false } ``` ## Common errors - `400 Bad Request` (`userMustBelongToOrg`) when your account has no organization - `401 Unauthorized` when you are not logged in - `403 Forbidden` (`forbidden`) when you are not an organization admin - `403 Forbidden` (`customerScopedTokenForbidden`) for a customer-scoped API token - `423 Locked` (`organizationSuspended`) when the organization was suspended by Uptimeify support or its data deletion has already started
### Add Custom Domain to Status Page
URL: https://docs.uptimeify.io/api/status-pages/add-status-page-domain
Description: Adds a custom hostname to an existing status page and returns the DNS TXT record needed for verification. Organization-wide: admin or editor; customer-bound: by the page's ownership class.
Summary: `POST /api/status-pages/domains` **Access:** Organization-wide callers need the role `admin` or `editor` (organization-wide `readonly` stays read-only). Customer-bound users (also with the role `readonly`) and customer-bound API tokens follow the page's ownership class instead: allowed on `self_service` pages, on `managed` pages only with the customer's `canEditManaged` exception, otherwise `403` with `data.code: managed_by_organization`. ## Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `statusPageId` | number \| string | Yes | The status page ID or publicId | | `hostname` | string | Yes | The custom hostname (e.g. `status.deinkunde.com`) | ## Example (cURL) ```bash curl -X POST "$BASE_URL/api/status-pages/domains" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "statusPageId": 1, "hostname": "status.deinkunde.com" }' ``` ## Response ```json { "domain": { "id": 42, "hostname": "status.deinkunde.com", "status": "pending", "role": "status_page", "verificationToken": "abc123-def456-ghi789", "verifiedAt": null, "lastVerificationError": null, "lastVerificationErrorAt": null, "createdAt": "2026-05-01T11:00:00.000Z", "updatedAt": "2026-05-01T11:00:00.000Z", "statusPageId": 1 }, "dns": { "txtName": "_verify-status.status.deinkunde.com", "txtValue": "abc123-def456-ghi789" } } ``` Same shape as [Get Status Page Domain](/api/status-pages/get-status-page-domain): `domain.statusPageId` is the numeric id of the status page the domain was added to, also when the request named it by publicId. ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` when you are an organization-wide caller without the role admin or editor - `403 Forbidden` (`managed_by_organization`) when you are customer-bound (user, also with the role `readonly`, or token) and the page is `managed` without the customer's `canEditManaged` exception - `404 Not found` when the status page does not exist - `409 Conflict` when the status page already has a domain (`domainAlreadyExists`) or your organization already has a row for this hostname (`hostnameAlreadyInUse`) - `400 Bad Request` when the hostname is invalid (`invalidHostname`) or reserved (`hostnameReserved`: the platform's own hosts and anything under `uptimeify.io`) A hostname is only claimed once it is **verified** or **active**. Another organization's unverified request does not block yours; the claim is decided at [Verify Status Page Domain](/api/status-pages/verify-status-page-domain). A `pending` request that is never verified is removed after 7 days.
### Cancel Status Page Maintenance
URL: https://docs.uptimeify.io/api/status-pages/cancel-status-page-maintenance
Description: Cancels an upcoming maintenance and tells the subscribers.
Summary: `POST /api/status-pages/maintenances/{id}/cancel` Cancels an upcoming maintenance (`state: scheduled`). It leaves the public page; subscribers who got the announcement (`notifyOnSchedule`) receive `maintenance_cancelled`, and the reminder and start messages are not sent. A running maintenance is ended with [Complete Maintenance](/api/status-pages/complete-status-page-maintenance). ## Access Organization-wide callers: `admin` and `editor` (organization-wide `readonly` stays read-only). Customer-bound users (also with the role `readonly`) and customer-bound API tokens follow the ownership class of every page involved (for a new maintenance each page in `statusPageIds`, otherwise every page the maintenance is linked to): allowed on `self_service` pages, on `managed` pages only with the customer's `canEditManaged` exception, otherwise `403` with `data.code: managed_by_organization`. A maintenance on no status page keeps the role rule (`admin` or `editor`). A customer-scoped user or API token only reaches maintenance whose status pages all belong to a customer in its scope; a page without a customer (`customerId: null`) is for organization-wide roles only. Maintenance of another organization answers `404` (`statusPageMaintenanceNotFound`). Path ids take the numeric id or the `publicId`. The change is written to the organization's audit log. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/status-pages/maintenances/12/cancel" \ -H "Authorization: Bearer $TOKEN" ``` ## Response `200 OK` with the maintenance, now `state: cancelled` and `cancelledAt` set. ## Common errors - `400 Bad Request` (`invalidIdentifier`) when an id is neither a number nor a UUID - `401 Unauthorized` when you are not logged in - `403 Forbidden` (`forbidden`) when your role may not do this, or for a customer-scoped caller on a page without a customer or of another customer - `403 Forbidden` (`managed_by_organization`) when you are customer-bound (user, also with the role `readonly`, or token) and a status page involved is `managed` without the customer's `canEditManaged` exception - `403 Forbidden` (`statusPagesModuleDisabled`) when the status pages module is not activated - `404 Not Found` (`statusPageMaintenanceNotFound`) when the maintenance does not exist or belongs to another organization - `409 Conflict` (`statusPageMaintenanceClosed`) when the maintenance is not upcoming (running, completed or already cancelled)
### Complete Status Page Maintenance
URL: https://docs.uptimeify.io/api/status-pages/complete-status-page-maintenance
Description: Ends a running maintenance now.
Summary: `POST /api/status-pages/maintenances/{id}/complete` Ends a running maintenance (`state: in_progress`) now: `scheduledUntil` becomes the current time. Subscribers get `maintenance_completed` (with `notifyOnComplete`) within a minute, as for a planned end. ## Access Organization-wide callers: `admin` and `editor` (organization-wide `readonly` stays read-only). Customer-bound users (also with the role `readonly`) and customer-bound API tokens follow the ownership class of every page involved (for a new maintenance each page in `statusPageIds`, otherwise every page the maintenance is linked to): allowed on `self_service` pages, on `managed` pages only with the customer's `canEditManaged` exception, otherwise `403` with `data.code: managed_by_organization`. A maintenance on no status page keeps the role rule (`admin` or `editor`). A customer-scoped user or API token only reaches maintenance whose status pages all belong to a customer in its scope; a page without a customer (`customerId: null`) is for organization-wide roles only. Maintenance of another organization answers `404` (`statusPageMaintenanceNotFound`). Path ids take the numeric id or the `publicId`. The change is written to the organization's audit log. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/status-pages/maintenances/12/complete" \ -H "Authorization: Bearer $TOKEN" ``` ## Response `200 OK` with the maintenance, now `state: completed`. ## Common errors - `400 Bad Request` (`invalidIdentifier`) when an id is neither a number nor a UUID - `401 Unauthorized` when you are not logged in - `403 Forbidden` (`forbidden`) when your role may not do this, or for a customer-scoped caller on a page without a customer or of another customer - `403 Forbidden` (`managed_by_organization`) when you are customer-bound (user, also with the role `readonly`, or token) and a status page involved is `managed` without the customer's `canEditManaged` exception - `403 Forbidden` (`statusPagesModuleDisabled`) when the status pages module is not activated - `404 Not Found` (`statusPageMaintenanceNotFound`) when the maintenance does not exist or belongs to another organization - `409 Conflict` (`statusPageMaintenanceClosed`) when the maintenance is not running
### Create Status Page
URL: https://docs.uptimeify.io/api/status-pages/create-status-page
Description: Creates a new status page. Requires the role `admin` or `editor`; customer-bound users and tokens (also `readonly`) create self-service pages of their customers.
Summary: `POST /api/status-pages` ## Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `customerId` | number | No | - | Customer ID (must belong to your organization). Omit it for a page of the whole organization, without a customer; only organization-wide roles and API tokens may create one. | | `includeCustomerMonitors` | boolean | No | `false` | Show every monitor of the customer, except those in `hiddenMonitors`, automatically after the explicit components, including monitors created later. Has no effect on a page without a customer. Until 28 October 2026 the default was `true` for a page with a customer; send `true` to keep that behavior. | | `managementType` | string | No | `managed` | `managed` or `self_service`, like monitors. Only organization admins may choose it; customer-bound users and tokens always create `self_service` pages. | | `name` | string | Yes | - | Display name (1-120 chars). Slug auto-generated from name. | | `slug` | string | No | auto | URL slug (1-120 chars, auto-normalized to lowercase-hyphens) | | `description` | string | No | null | Description (max 1000 chars) | | `visibility` | string | No | `public` | `public`, `customer_members_only`, `password_protected` (anyone with the page password, see below) or `sso_members_only` (like `customer_members_only`, and the session must come from your organization's single sign-on) | | `accessPassword` | string | No | - | Page password, 8-200 characters. Required with `visibility: password_protected`. Write-only: stored as a bcrypt hash and never returned; status page responses only show `hasPassword` and `accessPasswordSetAt`. | | `ipAllowlist` | array | No | `[]` | IPv4/IPv6 addresses or CIDR ranges (e.g. `203.0.113.0/24`, `2001:db8::/32`), at most 50. Only visitors from these networks see the page, on top of `visibility`. Stored normalized as `addr/prefix` (`203.0.113.7` becomes `203.0.113.7/32`), duplicates removed. `[]` = no IP restriction. | | `isPublished` | boolean | No | true | Whether the page is publicly visible | | `smsSubscriptionsEnabled` | boolean | No | `false` | Offer SMS subscriptions on the public page. Each SMS draws on your organization's SMS quota and stops at its SMS safety cap. Needs SMS quota (`403 smsQuotaRequired` otherwise). Shown to visitors only while the platform can send SMS and your organization has SMS quota. | | `pushSubscriptionsEnabled` | boolean | No | `false` | Offer browser push subscriptions on the public page. Shown to visitors only while the platform has VAPID keys. | | `customDomainHostname` | string | No | null | Custom domain (3-253 chars). Creates a pending DNS verification record. | | `hiddenMonitors` | array | No | `[]` | Monitors to hide from this status page. Each entry is `{ "type": "http"\|"dns"\|"icmp"\|"smtp"\|"ssh"\|"ftp"\|"imap_pop", "id": }`. Omit or send `[]` to show all monitors (the default). Monitors added later appear automatically. Maximum 500 entries. | **Private pages (since 28 October 2026).** - `password_protected`: anyone who knows the page password sees the page. Visitors unlock it with the [verify-password endpoint](/api/status-pages/get-public-status-page), which sets an access cookie for 30 days; without it the public page answers `401 passwordRequired`. Creating a page with `password_protected` and without `accessPassword` is rejected with `400 passwordRequired`. - `sso_members_only`: like `customer_members_only` (signed-in members of the customer, or of the organization for a page without a customer), and the session must have been created through your organization's single sign-on (OIDC or SAML). Not signed in, or signed in without SSO, the public page answers `401 ssoRequired`. While your organization has no verified SSO, the value is rejected with `400 ssoNotConfigured`. - `ipAllowlist` applies on top of every visibility: visitors from other networks get `403 statusPageIpNotAllowed`. The address that counts is…
### Create Status Page Component
URL: https://docs.uptimeify.io/api/status-pages/create-status-page-component
Description: Adds a monitor, a third-party provider or a manually maintained component to a status page.
Summary: `POST /api/status-pages/{id}/components` ## Access Organization `admin` and `editor`; customer-bound users (also `readonly`) and tokens only on `self_service` pages of their customers, or on `managed` ones with the customer's `canEditManaged` exception (otherwise `403 managed_by_organization`). A customer-scoped user or API token only reaches pages of a customer in its scope; a page without a customer (`customerId: null`) answers it with `403` (`forbidden`). A page of another organization answers `404` (`statusPageNotFound`). Path ids take the numeric id or the `publicId`. The change is written to the organization's audit log. ## Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `sourceKind` | string | Yes | - | `monitor` (state comes from a monitor), `dependency` (state comes from a third-party provider we monitor) or `manual` (you set the state). | | `monitorType` | string | With `monitor` | - | `http`, `dns`, `icmp`, `smtp`, `ssh`, `tcp`, `ftp` or `imap_pop`. Not allowed with `manual`. | | `monitorId` | number | With `monitor` | - | Numeric monitor id. Page with a customer: a monitor of that customer. Page without a customer: any monitor of your organization. Not allowed with `manual`. | | `dependencySlug` | string | With `dependency` | - | Slug of an active provider from `GET /api/public/dependencies`. Not allowed with the other kinds. | | `manualStatus` | string | No | `operational` | `manual` only: `operational`, `degraded`, `partial_outage`, `major_outage` or `maintenance`. | | `name` | string | With `manual` | monitor or provider name | Display name (1-120 chars). | | `description` | string\|null | No | `null` | Max 1000 chars. | | `groupId` | number\|string\|null | No | `null` | Id or `publicId` of a group of this page. | | `sort` | number | No | after the last component | Position, 0-100000. | | `showUptime` | boolean | No | `true` | Show the availability bar of this component. | A monitor can be a component of the same page only once. `hiddenMonitors` never hides an explicit component. When a monitor is deleted, its components disappear from every status page automatically. A `dependency` component shows the overall status we publish for that provider on our public dependency monitoring: `operational`, `degraded`, `partial_outage`, `major_outage`, `maintenance`, or `unknown` while we cannot see the provider (shown as a warning, but not counted in the page's overall state). An open incident linked to the component raises its state. A provider can be a component of the same page only once; there is no availability bar. When the provider's status changes, subscribers of the page (or of this component) are notified like for a monitor incident. No monitor and no customer are needed. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/status-pages/1/components" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "sourceKind": "monitor", "monitorType": "http", "monitorId": 101, "groupId": 3 }' ``` A manual component: ```bash curl -X POST "$BASE_URL/api/status-pages/1/components" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "sourceKind": "manual", "name": "Payment provider", "description": "Card payments at checkout" }' ``` A third-party provider: ```bash curl -X POST "$BASE_URL/api/status-pages/1/components" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "sourceKind": "dependency", "dependencySlug": "stripe" }' ``` ## Response `201 Created` with the new component: ```json { "id": 7, "publicId": "0b6f3c1e-8d2a-4f5b-9c7e-1a2b3c4d5e6f", "statusPageId": 1, "groupId": 3, "sort": 0, "name": "Main Site", "description": null, "showUptime": true, "sourceKind": "monitor", "monitorType": "http", "monitorId": 101, "manualStatus": null, "dependencySlug": null, "createdAt": "2026-10-27T09:00:00.000Z", "updatedA…
### Create Status Page Component Group
URL: https://docs.uptimeify.io/api/status-pages/create-status-page-component-group
Description: Adds a component group to a status page.
Summary: `POST /api/status-pages/{id}/groups` ## Access Organization `admin` and `editor`; customer-bound users (also `readonly`) and tokens only on `self_service` pages of their customers, or on `managed` ones with the customer's `canEditManaged` exception (otherwise `403 managed_by_organization`). A customer-scoped user or API token only reaches pages of a customer in its scope; a page without a customer (`customerId: null`) answers it with `403` (`forbidden`). A page of another organization answers `404` (`statusPageNotFound`). Path ids take the numeric id or the `publicId`. The change is written to the organization's audit log. ## Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `name` | string | Yes | - | Heading of the group (1-120 chars). | | `sort` | number | No | after the last group | Position, 0-100000. | | `collapsed` | boolean | No | `false` | Start collapsed on the public page. | Put components into the group with `groupId` on [Create Status Page Component](/api/status-pages/create-status-page-component), [Update Status Page Component](/api/status-pages/update-status-page-component) or [Reorder Status Page Components](/api/status-pages/reorder-status-page-components). ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/status-pages/1/groups" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Core services" }' ``` ## Response `201 Created` with the new group: ```json { "id": 3, "publicId": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b", "statusPageId": 1, "name": "Core services", "sort": 0, "collapsed": false, "createdAt": "2026-10-27T08:55:00.000Z", "updatedAt": "2026-10-27T08:55:00.000Z" } ``` ## Common errors - `400 Bad Request` (`invalidRequestBody`) when `name` is missing or a field is invalid - `400 Bad Request` (`invalidIdentifier`) when an id in the path is neither a number nor a UUID - `401 Unauthorized` when you are not logged in - `403 Forbidden` (`forbidden`) when your role may not do this, or for a customer-scoped caller on a page without a customer or of another customer - `403 Forbidden` (`statusPagesModuleDisabled`) when the status pages module is not activated - `404 Not Found` (`statusPageNotFound`) when the status page does not exist or belongs to another organization - `409 Conflict` (`statusPageLimitReached`, with `data.max`) when the page already has 500 groups
### Schedule Status Page Maintenance
URL: https://docs.uptimeify.io/api/status-pages/create-status-page-maintenance
Description: Schedules maintenance for status pages and components, with announcement, reminder, start and end messages.
Summary: `POST /api/status-pages/maintenances` `state` comes from the clock and is never stored: `scheduled` before `scheduledFor`, `in_progress` until `scheduledUntil`, then `completed`; `cancelled` once cancelled. The maintenance starts and ends by itself, no call is needed. While it is `in_progress` its components show `maintenance` on the public page (a worse state, such as an outage, stays), a maintenance without components shows the whole page as under maintenance. Subscribers of the status page (or of an affected component) are notified through their channel (email, webhook, Slack, Teams) with the events `maintenance_scheduled` (when saved, and again when an upcoming start is moved), `maintenance_reminder`, `maintenance_started`, `maintenance_completed`, `maintenance_update` and `maintenance_cancelled`. The switches below decide which of them are sent; every event also appears in the page's RSS and Atom feed. Sending honours the page's subscription delay and is decided at send time: a moved or cancelled maintenance does not send its outdated messages. Maintenance here informs the visitors of your status pages. It does not pause monitor alerts: for that create a [maintenance window](/api/maintenance-windows) in monitoring, which also appears on pages that show those monitors. ## Access Organization-wide callers: `admin` and `editor` (organization-wide `readonly` stays read-only). Customer-bound users (also with the role `readonly`) and customer-bound API tokens follow the ownership class of every page involved (for a new maintenance each page in `statusPageIds`, otherwise every page the maintenance is linked to): allowed on `self_service` pages, on `managed` pages only with the customer's `canEditManaged` exception, otherwise `403` with `data.code: managed_by_organization`. A maintenance on no status page keeps the role rule (`admin` or `editor`). A customer-scoped user or API token only reaches maintenance whose status pages all belong to a customer in its scope; a page without a customer (`customerId: null`) is for organization-wide roles only. Maintenance of another organization answers `404` (`statusPageMaintenanceNotFound`). Path ids take the numeric id or the `publicId`. The change is written to the organization's audit log. ## Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `title` | string | Yes | - | Shown on the page and in every message (1-200 chars). | | `description` | string\|null | No | `null` | What happens and what visitors notice (max 5000 chars). | | `scheduledFor` | string | Yes | - | Start, ISO 8601 with offset (`Z` or `+01:00`); stored and returned in UTC. | | `scheduledUntil` | string | Yes | - | End, after `scheduledFor`. | | `statusPageIds` | array | Yes | - | Status pages (id or `publicId`, 1-10) that show the maintenance. | | `componentIds` | array | No | `[]` | Affected components (id or `publicId`, up to 500) of any source: manual, monitor or third-party. Each must belong to one of `statusPageIds`. A page without a listed component shows the maintenance page-wide. | | `notifyOnSchedule` | boolean | No | `true` | Announce to subscribers when saved, and again when an upcoming start is moved. | | `reminderMinutesBefore` | number\|null | No | `null` | Remind subscribers this many minutes (5-10080) before the start; `null` sends no reminder. | | `notifyOnStart` | boolean | No | `false` | Notify subscribers when the maintenance starts. | | `notifyOnComplete` | boolean | No | `true` | Notify subscribers when it ends. | Unknown fields are rejected. A maintenance that lies entirely in the past is stored without an announcement. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/status-pages/maintenances" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"title": "Database upgrade", "scheduledFor": "2026-11-03T23:00:00+01:00", "scheduledUntil": "2026-1…
### Create Status Page Template
URL: https://docs.uptimeify.io/api/status-pages/create-status-page-template
Description: Creates an incident or update template.
Summary: `POST /api/status-pages/templates` A template pre-fills the form for a new public incident (`kind: incident`) or for an update on a running one (`kind: update`). It publishes nothing by itself; incidents are still created with [Create Manual Incident](/api/monitoring/create-manual-incident). ## Access Organization `admin` and `editor` with an unrestricted scope: a customer-scoped user or API token gets `403` (`customerScopedTokenForbidden`), because a template belongs to the whole organization. A template of another organization answers `404` (`statusPageTemplateNotFound`). Path ids take the numeric id or the `publicId`. The change is written to the organization's audit log. ## Request Body | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `kind` | string | Yes | - | `incident` (a new incident) or `update` (an update on a running one). Cannot be changed later. | | `name` | string | Yes | - | Shown in the template picker, 1-120 characters. | | `title` | string or null | No | `null` | Incident templates only: the incident title, up to 200 characters. | | `body` | string | Yes | - | The update text, 1-5,000 characters. | | `updateStatus` | string | No | `investigating` | Phase the update starts with: `investigating`, `identified`, `monitoring` or `resolved`. | | `severity` | string or null | No | `null` | Incident templates only: `minor`, `major`, `critical` or `maintenance`. | | `impact` | string or null | No | `null` | Incident templates only: `degraded`, `partial_outage`, `major_outage` or `maintenance`. | | `statusPageIds` | array or null | No | `null` | Incident templates only: status pages (id or publicId) preselected in the form, at most 10. Each must belong to your organization. | | `componentIds` | array or null | No | `null` | Incident templates only: components (id or publicId), at most 100; each must belong to one of `statusPageIds`. | An update template (`kind: update`) takes only `name`, `body` and `updateStatus`; the incident-only fields stay `null`. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X POST "$BASE_URL/api/status-pages/templates" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "kind": "incident", "name": "Payment provider down", "title": "Card payments failing", "body": "We are looking into failed card payments.", "severity": "major", "statusPageIds": [2], "componentIds": [8] }' ``` ## Response `201 Created` with the new template: ```json { "id": 4, "publicId": "3f6c2a1b-8d4e-4b7a-9c1d-2e3f4a5b6c7d", "kind": "incident", "name": "Payment provider down", "title": "Card payments failing", "body": "We are looking into failed card payments.", "updateStatus": "investigating", "severity": "major", "impact": "partial_outage", "statusPageIds": [2], "componentIds": [8], "createdAt": "2026-10-27T09:00:00.000Z", "updatedAt": "2026-10-27T09:00:00.000Z" } ``` ## Common errors - `400 Bad Request` (`invalidRequestBody`) when a field is invalid, or an update template gets an incident-only field - `400 Bad Request` (`statusPageIdsRequired`) when `componentIds` is sent without `statusPageIds` - `400 Bad Request` (`statusPageComponentNotOnPage`) when a component belongs to a page that is not in `statusPageIds` - `404 Not Found` (`statusPageNotFound`, `statusPageComponentNotFound`) when a page or component does not exist in your organization - `409 Conflict` (`statusPageLimitReached`, with `data.max`) when the organization already has 200 templates - `401 Unauthorized` when you are not logged in - `403 Forbidden` (`statusPagesModuleDisabled`) when the status pages module is not activated - `403 Forbidden` (`forbidden`) when your role may not write - `403 Forbidden` (`customerScopedTokenForbidden`) for a customer-scoped user or token
### Delete Status Page
URL: https://docs.uptimeify.io/api/status-pages/delete-status-page
Description: Permanently deletes a status page. Requires the role `admin` or `editor`.
Summary: `DELETE /api/status-pages/:id` ## Example (cURL) ```bash curl -X DELETE "$BASE_URL/api/status-pages/1" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "deleted": true, "id": 1 } ``` ## Common errors - `401 Unauthorized` when not authenticated - `403 Forbidden` (`forbidden`) when the role is neither `admin` nor `editor` (for example `readonly`, global supporter) - `403 Forbidden` (`managed_by_organization`) when a customer-bound token deletes a `managed` page without the customer's `canEditManaged` exception - `404 Not found` when the status page does not exist
### Delete Status Page Component
URL: https://docs.uptimeify.io/api/status-pages/delete-status-page-component
Description: Removes a component from a status page.
Summary: `DELETE /api/status-pages/{id}/components/{componentId}` Removes the component from the page. The monitor itself is not touched. If the page includes the customer's monitors automatically (`includeCustomerMonitors`), a monitor of that customer still appears there after its component is deleted, unless it is in `hiddenMonitors`. ## Access Organization `admin` and `editor`; customer-bound users (also `readonly`) and tokens only on `self_service` pages of their customers, or on `managed` ones with the customer's `canEditManaged` exception (otherwise `403 managed_by_organization`). A customer-scoped user or API token only reaches pages of a customer in its scope; a page without a customer (`customerId: null`) answers it with `403` (`forbidden`). A page of another organization answers `404` (`statusPageNotFound`). Path ids take the numeric id or the `publicId`. The change is written to the organization's audit log. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X DELETE "$BASE_URL/api/status-pages/1/components/8" \ -H "Authorization: Bearer $TOKEN" ``` ## Response `204 No Content` without a body. ## Common errors - `400 Bad Request` (`invalidIdentifier`) when an id in the path is neither a number nor a UUID - `401 Unauthorized` when you are not logged in - `403 Forbidden` (`forbidden`) when your role may not do this, or for a customer-scoped caller on a page without a customer or of another customer - `403 Forbidden` (`statusPagesModuleDisabled`) when the status pages module is not activated - `404 Not Found` (`statusPageNotFound`) when the status page does not exist or belongs to another organization - `404 Not Found` (`statusPageComponentNotFound`) when the component does not exist on this page
### Delete Status Page Component Group
URL: https://docs.uptimeify.io/api/status-pages/delete-status-page-component-group
Description: Deletes a component group; its components stay on the page without a group.
Summary: `DELETE /api/status-pages/{id}/groups/{groupId}` Deletes only the group. Its components stay on the page, without a group (`groupId: null`). ## Access Organization `admin` and `editor`; customer-bound users (also `readonly`) and tokens only on `self_service` pages of their customers, or on `managed` ones with the customer's `canEditManaged` exception (otherwise `403 managed_by_organization`). A customer-scoped user or API token only reaches pages of a customer in its scope; a page without a customer (`customerId: null`) answers it with `403` (`forbidden`). A page of another organization answers `404` (`statusPageNotFound`). Path ids take the numeric id or the `publicId`. The change is written to the organization's audit log. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X DELETE "$BASE_URL/api/status-pages/1/groups/3" \ -H "Authorization: Bearer $TOKEN" ``` ## Response `204 No Content` without a body. ## Common errors - `400 Bad Request` (`invalidIdentifier`) when an id in the path is neither a number nor a UUID - `401 Unauthorized` when you are not logged in - `403 Forbidden` (`forbidden`) when your role may not do this, or for a customer-scoped caller on a page without a customer or of another customer - `403 Forbidden` (`statusPagesModuleDisabled`) when the status pages module is not activated - `404 Not Found` (`statusPageNotFound`) when the status page does not exist or belongs to another organization - `404 Not Found` (`statusPageComponentGroupNotFound`) when the group does not exist on this page
### Delete Status Page Maintenance
URL: https://docs.uptimeify.io/api/status-pages/delete-status-page-maintenance
Description: Deletes a maintenance from every page and the feed.
Summary: `DELETE /api/status-pages/maintenances/{id}` Deletes the maintenance with its updates and its subscription events: it disappears from every page and from the feed, and messages not yet sent are not sent. To keep it in the history, cancel it instead: [Cancel Maintenance](/api/status-pages/cancel-status-page-maintenance). ## Access Organization-wide callers: `admin` and `editor` (organization-wide `readonly` stays read-only). Customer-bound users (also with the role `readonly`) and customer-bound API tokens follow the ownership class of every page involved (for a new maintenance each page in `statusPageIds`, otherwise every page the maintenance is linked to): allowed on `self_service` pages, on `managed` pages only with the customer's `canEditManaged` exception, otherwise `403` with `data.code: managed_by_organization`. A maintenance on no status page keeps the role rule (`admin` or `editor`). A customer-scoped user or API token only reaches maintenance whose status pages all belong to a customer in its scope; a page without a customer (`customerId: null`) is for organization-wide roles only. Maintenance of another organization answers `404` (`statusPageMaintenanceNotFound`). Path ids take the numeric id or the `publicId`. The change is written to the organization's audit log. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X DELETE "$BASE_URL/api/status-pages/maintenances/12" \ -H "Authorization: Bearer $TOKEN" ``` ## Response `204 No Content` without a body. A second call answers `404`. ## Common errors - `400 Bad Request` (`invalidIdentifier`) when an id is neither a number nor a UUID - `401 Unauthorized` when you are not logged in - `403 Forbidden` (`forbidden`) when your role may not do this, or for a customer-scoped caller on a page without a customer or of another customer - `403 Forbidden` (`managed_by_organization`) when you are customer-bound (user, also with the role `readonly`, or token) and a status page involved is `managed` without the customer's `canEditManaged` exception - `403 Forbidden` (`statusPagesModuleDisabled`) when the status pages module is not activated - `404 Not Found` (`statusPageMaintenanceNotFound`) when the maintenance does not exist or belongs to another organization
### Delete Status Page Template
URL: https://docs.uptimeify.io/api/status-pages/delete-status-page-template
Description: Deletes a template. Incidents created from it stay as they are.
Summary: `DELETE /api/status-pages/templates/{id}` A template pre-fills the form for a new public incident (`kind: incident`) or for an update on a running one (`kind: update`). It publishes nothing by itself; incidents are still created with [Create Manual Incident](/api/monitoring/create-manual-incident). ## Access Organization `admin` and `editor` with an unrestricted scope: a customer-scoped user or API token gets `403` (`customerScopedTokenForbidden`), because a template belongs to the whole organization. A template of another organization answers `404` (`statusPageTemplateNotFound`). Path ids take the numeric id or the `publicId`. The change is written to the organization's audit log. ## Example (cURL) ```bash BASE_URL="https://uptimeify.io" TOKEN="" curl -X DELETE "$BASE_URL/api/status-pages/templates/4" \ -H "Authorization: Bearer $TOKEN" ``` ## Response `204 No Content`, no body. A second DELETE answers `404`. ## Common errors - `400 Bad Request` (`invalidIdentifier`) when the id is neither a number nor a UUID - `404 Not Found` (`statusPageTemplateNotFound`) when the template does not exist or belongs to another organization - `401 Unauthorized` when you are not logged in - `403 Forbidden` (`statusPagesModuleDisabled`) when the status pages module is not activated - `403 Forbidden` (`forbidden`) when your role may not write - `403 Forbidden` (`customerScopedTokenForbidden`) for a customer-scoped user or token
### Delete Status Page Subscriber
URL: https://docs.uptimeify.io/api/status-pages/delete-subscriber
Description: Permanently deletes a subscriber and its stored consent evidence. Organization-wide: admin or editor; customer-bound: by the page's ownership class.
Summary: `DELETE /api/status-pages/:id/subscribers/:subscriberId` **Access:** Organization-wide callers need the role `admin` or `editor` (organization-wide `readonly` stays read-only). Customer-bound users (also with the role `readonly`) and customer-bound API tokens follow the page's ownership class instead: allowed on `self_service` pages, on `managed` pages only with the customer's `canEditManaged` exception, otherwise `403` with `data.code: managed_by_organization`. This is a **hard delete**, not the public one-click unsubscribe. The public unsubscribe link keeps the subscriber row with `status: "unsubscribed"` as proof that sending must stop; this endpoint exists to answer erasure requests (GDPR Art. 17), so it removes the row entirely, email address, consent timestamp, IP address, and user agent included. ## Path Parameters | Parameter | Description | |-----------|-------------| | `id` | Status page ID or `publicId` (UUID) | | `subscriberId` | Subscriber ID (positive integer) | ## Example (cURL) ```bash curl -X DELETE "$BASE_URL/api/status-pages/db58058e-4b58-4d97-a314-3bb8e279a182/subscribers/42" \ -H "Authorization: Bearer $TOKEN" ``` ## Response ```json { "ok": true } ``` ## Common errors - `401 Unauthorized` when you are not authenticated - `400 User must belong to an organization` (`data.code: userMustBelongToOrg`) when no organization can be derived from the session or token - `403 Forbidden` when you are an organization-wide caller without the role admin or editor, or your customer scope does not include this status page - `403 Forbidden` (`managed_by_organization`) when you are customer-bound (user, also with the role `readonly`, or token) and the page is `managed` without the customer's `canEditManaged` exception - `400 Invalid Status page identifier` when `id` is not a valid numeric ID or UUID (no `data.code`) - `404 Status page not found` when `id` is well-formed but no status page has that ID (no `data.code`) - `404 Status page not found` (`data.code: statusPageNotFound`) when `id` resolves to a real status page, but it belongs to a different organization, or is outside your customer scope - `400 Invalid subscriber id` (`data.code: invalidSubscriberId`) when `subscriberId` does not parse as a positive integer - `404 Subscriber not found` (`data.code: subscriberNotFound`) when `subscriberId` does not exist, or belongs to a different status page than `id` `id` is resolved and scope-checked before `subscriberId` is parsed, so a bad `id` is always the error you see first.
### Export Subscribers of All Status Pages
URL: https://docs.uptimeify.io/api/status-pages/export-all-subscribers
Description: Downloads the subscribers of the status pages you select as CSV, with the same filters as the list. Organization-wide: admin or editor; customer-bound: the pages you may maintain.
Summary: `GET /api/status-pages/subscribers/export` **Access:** organization-wide callers need the role `admin` or `editor`. Customer-bound users (also with the role `readonly`) and customer-bound API tokens get only the subscribers of pages they may maintain: `self_service` pages, and `managed` pages of customers with the `canEditManaged` exception. Subscribers of other pages are left out without an error. Same rows and filters as [List Subscribers of All Status Pages](/api/status-pages/list-all-subscribers) (`statusPageId`, `statusPageIds`, `channel`, `status`, `search`), without paging. **A page selection is required.** Name the pages with `statusPageIds` (comma-separated IDs or `publicId`s, at most 50) or `statusPageId`. Subscribers of different pages often belong to different data controllers, so an export never mixes pages implicitly. A selected page outside your scope contributes no rows. Every export is recorded in your organization's audit log (row count and the filters used, never the addresses themselves). ## Example (cURL) ```bash curl "$BASE_URL/api/status-pages/subscribers/export?statusPageIds=db58058e-4b58-4d97-a314-3bb8e279a182&channel=email" \ -H "Authorization: Bearer $TOKEN" \ -o subscribers.csv ``` ## Response `200 OK` with `Content-Type: text/csv; charset=utf-8` and `Content-Disposition: attachment; filename="status-page-subscribers.csv"`. ```csv "status_page","status_page_id","email","status","locale","created_at","confirmed_at","channel","target","component_ids" "Acme Status","db58058e-4b58-4d97-a314-3bb8e279a182","reader@example.com","confirmed","en","2026-08-01T12:00:00.000Z","2026-08-01T12:05:00.000Z","email","","" ``` `status_page_id` is the page's `publicId`. `target` is the origin of the target URL only, as in the list. `component_ids` are space separated, empty for the whole page. Every cell is quoted, and a leading `=`, `+`, `-` or `@` is neutralized against formula injection. ## Common errors Same as [List Subscribers of All Status Pages](/api/status-pages/list-all-subscribers), plus: - `400 Bad Request` (`data.code: invalidRequestBody`) when neither `statusPageIds` nor `statusPageId` is given
### Export Status Page Subscribers
URL: https://docs.uptimeify.io/api/status-pages/export-subscribers
Description: Downloads every subscriber of a status page as CSV. Organization-wide: admin or editor; customer-bound: by the page's ownership class.
Summary: `GET /api/status-pages/:id/subscribers/export` **Access:** Organization-wide callers need the role `admin` or `editor` (organization-wide `readonly` stays read-only). Customer-bound users (also with the role `readonly`) and customer-bound API tokens follow the page's ownership class instead: allowed on `self_service` pages, on `managed` pages only with the customer's `canEditManaged` exception, otherwise `403` with `data.code: managed_by_organization`. Subscriber addresses are personal data, so reading them takes the same right as changing the page. Unlike [List Status Page Subscribers](/api/status-pages/list-subscribers), the export is not capped, it returns every row for the page. Each export is recorded in the organization's audit log (page ID and row count only, never the addresses themselves), since this is a bulk download of your subscribers' personal data. ## Path Parameter | Parameter | Description | |-----------|-------------| | `id` | Status page ID or `publicId` (UUID) | ## Example (cURL) ```bash curl "$BASE_URL/api/status-pages/db58058e-4b58-4d97-a314-3bb8e279a182/subscribers/export" \ -H "Authorization: Bearer $TOKEN" \ -o subscribers.csv ``` ## Response `Content-Type: text/csv; charset=utf-8`, `Content-Disposition: attachment; filename="status-page--subscribers.csv"` (`` is the status page's numeric ID, not its `publicId`). ```csv "email","status","locale","created_at","confirmed_at","channel","target","component_ids" "reader@example.com","confirmed","en","2026-08-01T12:00:00.000Z","2026-08-01T12:05:00.000Z","email","","" "other@example.com","pending","de","2026-08-02T09:30:00.000Z","","email","","" "","confirmed","de","2026-10-27T09:00:00.000Z","2026-10-27T09:01:00.000Z","slack","https://hooks.slack.com/…","12 14" ``` `channel`, `target` and `component_ids` follow the original five columns. `target` is the origin of a webhook, Slack, Teams or push target only, never the full URL, and for SMS the masked number (`+49…67`); `component_ids` is a space separated list, empty for the whole page. Rows are ordered newest-first by `created_at`. Every field is quoted and embedded quotes are doubled per RFC 4180. A value that would otherwise start with `=`, `+`, `-`, or `@`, or with these characters when preceded by whitespace (tab, space, or carriage return), is prefixed with a single quote so it renders as inert text instead of being evaluated. Subscriber emails are visitor-supplied, so this guards against CSV/formula injection when the file is opened in Excel or Sheets. ## Common errors - `401 Unauthorized` when you are not authenticated - `400 User must belong to an organization` (`data.code: userMustBelongToOrg`) when no organization can be derived from the session or token - `403 Forbidden` when you are an organization-wide caller without the role admin or editor, or your customer scope does not include this status page - `403 Forbidden` (`managed_by_organization`) when you are customer-bound (user, also with the role `readonly`, or token) and the page is `managed` without the customer's `canEditManaged` exception - `400 Invalid Status page identifier` when `id` is not a valid numeric ID or UUID (no `data.code`) - `404 Status page not found` when `id` is well-formed but no status page has that ID (no `data.code`) - `404 Status page not found` (`data.code: statusPageNotFound`) when `id` resolves to a real status page, but it belongs to a different organization, or is outside your customer scope
### Get Public Status Page
URL: https://docs.uptimeify.io/api/status-pages/get-public-status-page
Description: Two endpoints serve the public status page view:
Summary: - `GET /api/status-pages/public/:slug`: lookup by URL slug - `GET /api/status-pages/public/by-id/:id`: lookup by numeric ID No authentication required for `visibility: public` pages. Customer-member authentication required for `visibility: customer_members_only` pages. A `customer_members_only` page without a customer is open to every logged-in member of its organization. Pages with `visibility: sso_members_only` work like `customer_members_only` and additionally require a session created through the organization's single sign-on: not signed in, or signed in without SSO, both endpoints answer `401 ssoRequired`. Pages with `visibility: password_protected` need the page password: without a valid access cookie both endpoints answer `401 passwordRequired`. The visitor unlocks the page with: `POST /api/status-pages/public/:slug/verify-password` ```json { "password": "the page password" } ``` The answer is `{ "ok": true }` and sets the httpOnly cookie `sp_access_